csApplicationFramework Class Reference
[Application Framework]

Application framework class. More...

#include <cstool/csapplicationframework.h>

Inheritance diagram for csApplicationFramework:


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]

Returns a pointer to the object registry.

Definition at line 274 of file csapplicationframework.h.

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().

See also:: Notes about string formatting in Crystal Space

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().

See also:: Notes about string formatting in Crystal Space

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().

See also:: Notes about string formatting in Crystal Space

Definition at line 384 of file csapplicationframework.h.

References CS_REPORTER_SEVERITY_WARNING, and csReportV.

void csApplicationFramework::Restart ( )

Restart application.

Remarks:: This method internally uses Quit().

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

Public API Reference

csApplicationFramework Class Reference [Application Framework]

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

csApplicationFramework Class Reference
[Application Framework]