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.


Static Public Methods

void Quit (void)
 Quit running the appliation.

iObjectRegistryGetObjectRegistry ()
 Returns a pointer to the object registry.

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

void ProcessQueue ()
 Start event queue.

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

void DisplayInfo (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.


Detailed Description

Application framework class.

Remarks:
In order to properly use this class, you must derive a class from it and provide 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). The library containing the implementation of this class contains an implementation of the main() function that controls the use of this class. When using the csApplicationFramework class, do not provide your own implementation of main(). In your source code create a global instance of the overridden object, as follows:
 // Example.h
 class myDerivedEngine : public csApplicationFramework
 {
 public:
   myDerivedEngine();
   virtual bool OnInitialize();
   virtual bool Application();
 };

 extern myDerivedEngine myApp;


 //--------------------------

 // Example.cpp
 // File scope
 myDerivedEngine myApp;

 myDerivedEngine::myDerivedEngine() : myDerivedEngine()
 {
   SetApplicationName ("crystal.space.example.app");
 }

 myDerivedEngine::OnIntialize()
 {
   // Request plugins, initialize any global non-CS data and structures
   return true;
 }
 
 myDerivedEngine::Application()
 {
   // Perform initialization of CS data and structures, set event handler,
   // load world, etc.

   if ( ! Open())
   {
     return false;
   }

   ProcessQueue();

   return true;
 }

This class 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 other classes related to the CSWS.

Definition at line 98 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::DisplayError 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 311 of file csapplicationframework.h.

References CS_REPORTER_SEVERITY_ERROR, and csReport.

void csApplicationFramework::DisplayInfo 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 325 of file csapplicationframework.h.

References CS_REPORTER_SEVERITY_NOTIFY, and csReport.

iObjectRegistry* csApplicationFramework::GetObjectRegistry   [inline, static]
 

Returns a pointer to the object registry.

Definition at line 245 of file csapplicationframework.h.

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

void csApplicationFramework::ProcessQueue   [inline, static]
 

Start event queue.

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

Definition at line 284 of file csapplicationframework.h.

References csDefaultRunLoop().

void csApplicationFramework::Quit void    [static]
 

Quit running the appliation.

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.

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.

Definition at line 274 of file csapplicationframework.h.


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