Home - Forums - Documentation - Gallery - Bugs
m (→The header)
(Radical changes in the step 4, new theme)
Line 1: Line 1:
[[Category:Tutorial]]
[[Category:Tutorial]]
-
= Step Four: : Using CEGUI =
+
= Step Four: : Setup the logging system =
== Introduction ==
== Introduction ==
-
In this tutorial we will create our applications’ windows with the help of CEGUI. This tutorial contains basic information only about the library , when CEGUI is new for you, please visit the project website for more information:
+
The ''Crystal Space SDK '' contents a built-in reporter system. You can sending messages to the following places:
-
[http://www.cegui.org.uk www.cegui.org.uk]
+
* stdout : Your message will be sent to the standard output.
 +
* stderr : Your message will be sent to standard error channel.
 +
* alert : Your message will be displayed in a information window.
 +
* console: Your message will be displayed on the console output.
 +
* debug : Your massage will be logged into the debug log file.
 +
* popup :
-
The CS SDK has the '''Ceguitest''' demo, a basic example, how you can integrate CEGUI into your application. The '''viewmesh'' test application uses also CEGUI, here you can find a long and detailed example, how to deal with this impressive windowing system under CS.
+
==Adding some log-related config options ==
-
== Important notes ==
+
Let's create an optional log file. First, we add to our ''cim.cfg'' the following options:
-
Some notes about CEGUI under CS. There is an introduction to Cegui in the manual, please read this section first. I cite the most important section:
+
Cim.Settings.EnableLogging = true;
 +
Cim.Settings.DebugFileName = /cim/debug.log
 +
Cim.Settings.AppendLogFile = false
 +
When the ''EnableLogging'' option is true, the game writes the report messages in the log file. The ''DebugFileName'' decides the name of the log file. The ''AppendLogFile '' option controls, the app creates a new log file or appends the messages to the old one (if any).
 +
 +
Ok, let's go to load this options in the ''cimGame::LoadConfig()'':
<pre>
<pre>
-
It is important that applications using CEGUI from Crystal Space do not use any of
+
bool cimGame::LoadConfig()
-
the CEGUI getSingleton() or getSingletonPtr() calls, such as
+
{
-
CEGUI::Singleton<T>::getSingleton() or CEGUI::System::getSingleton(). The reason
+
csRef<iConfigManager> confman (CS_QUERY_REGISTRY (GetObjectRegistry(), iConfigManager));
-
for this is that global and static variables (declared in methods, classes,
+
startmap = confman->GetStr("Cim.Settings.StartLevel","terrain");
-
namespaces, or globally) are not normally shared between modules. Calling
+
use_console = confman->GetBool("Cim.Settings.EnableConsole",false);
-
getSingleton() from the Crystal Space application will not necessarily return
+
enable_logging = confman->GetBool("Cim.Settings.EnableLogging",false);
-
the same instance as calling getSingleton() from the CEGUI plugin.
+
debug_filename = confman->GetStr("Cim.Settings.DebugFileName","/cim/debug.log");
 +
append_logfile = confman->GetBool("Cim.Settings.AppendLogFile",true);
 +
return true;
 +
}
</pre>
</pre>
-
Don't forget to link the CEGUIBase* library, when you build this demo. The correct name is depend on your build system. When you use '''MSVC8''', you need ''CEGUIBase-vc8_d.lib'' (in debug mode) or ''CEGUIBase-vc8.lib '' in release mode. These are in your ''CS\libs\csutil\win32\libs'' folder.
 
 +
== Listening the reports ==
-
== Loading CEGUI plugin ==
+
''Crystal Space '' provides us the ''iStandardReporterListener'' interface to do this. Let's query this:
-
 
+
-
To load CEGUI plugin, first we need change the ''cimGame::OnInitialize '' al little bit:
+
<pre>
<pre>
-
if (!csInitializer::RequestPlugins(object_reg = GetObjectRegistry(),
+
listener = CS_QUERY_REGISTRY(GetObjectRegistry(),iStandardReporterListener);
-
CS_REQUEST_VFS,
+
-
CS_REQUEST_OPENGL3D,
+
-
CS_REQUEST_ENGINE,
+
-
CS_REQUEST_FONTSERVER,
+
-
CS_REQUEST_IMAGELOADER,
+
-
CS_REQUEST_LEVELLOADER,
+
-
CS_REQUEST_REPORTER,
+
-
CS_REQUEST_REPORTERLISTENER,
+
-
CS_REQUEST_PLUGIN("crystalspace.collisiondetection.opcode",
+
-
iCollideSystem),
+
-
CS_REQUEST_PLUGIN("crystalspace.console.output.standard",
+
-
iConsoleOutput),
+
-
CS_REQUEST_PLUGIN ("crystalspace.cegui.wrapper", iCEGUI),
+
-
CS_REQUEST_END))
+
-
return ReportError("Failed to initialize plugins!");
+
</pre>
</pre>
-
The ''CS_REQUEST_PLUGIN ("crystalspace.cegui.wrapper", iCEGUI)'' will load the CEGUI plugin.
+
Ok, we have a the listener, let's customize it. As we said, Crystal Space ensures you many channel to your reports. Crystal Space uses 5 severity level:
-
We introduce a new class to handle the interface of our game. This new ''cimGuiHandler'' class qwill:
+
* CS_REPORTER_SEVERITY_BUG: his is the worst thing that can happen. It means that some code detected a bug in Crystal Space.
 +
* CS_REPORTER_SEVERITY_ERROR: There was an error of some kind. Usually this is an error while reading data.
 +
* CS_REPORTER_SEVERITY_WARNING: There was some condition which is non fatal but is suspicious.
-
* initialize CEGUI plugin, loading skin and layouts.
+
* CS_REPORTER_SEVERITY_NOTIFY: This is for debugging and it will usually generate an entry in some log.
-
* render CEGUI interface, show the actual window
+
-
* encapsulate all CEGUI callback functions
+
-
== The header ==
+
We can define, on what messaging channel listening what severity levels.
 +
iStandardReporterLIstener has a SetMessageDestination function:
<pre>
<pre>
-
class cimGuiHandler
+
virtual void SetMessageDestination (int severity,
-
{
+
bool do_stdout, bool do_stderr, bool do_console,
-
public:
+
bool do_alert, bool do_debug, bool do_popup = false) = 0;
-
 
+
-
bool Initialize(iObjectRegistry* obj_reg);
+
</pre>
</pre>
-
Yes, initializing. This function will intiailaze CEGUI and the event handler.
+
 
 +
We want to use the ''standard output'', the ''console'' and the ''debug file''. So the code is:
<pre>
<pre>
-
 
+
listener->SetMessageDestination(CS_REPORTER_SEVERITY_ERROR,true,false,true,false,true,false);
-
bool HandleEvent(iEvent& ev);
+
listener->SetMessageDestination(CS_REPORTER_SEVERITY_WARNING,true,false,true,false,true,false);
-
+
listener->SetMessageDestination(CS_REPORTER_SEVERITY_NOTIFY,true,false,true,false,true,false);
-
struct EventHandler : public scfImplementation1<EventHandler, iEventHandler>
+
listener->SetMessageDestination(CS_REPORTER_SEVERITY_DEBUG,true,false,true,false,true,false);
-
{
+
-
cimGui* parent;
+
-
 
+
-
EventHandler (cimGui* parent) : scfImplementationType (this),
+
-
parent (parent) {}
+
-
 
+
-
virtual ~EventHandler() {}
+
-
 
+
-
virtual bool HandleEvent (iEvent& e) { return parent->HandleEvent(e); }
+
-
CS_EVENTHANDLER_NAMES("cim.gui")
+
-
CS_EVENTHANDLER_NIL_CONSTRAINTS
+
-
};
+
</pre>
</pre>
-
We need an event handler to subscribe to the PostProcess event. We will render cegui in this phase. The solution is same, as in the prvious tutorial.
 
 +
Now we set up the log filename:
<pre>
<pre>
-
private:
+
listener->SetDebugFile(debug_filename,append_logfile);
-
 
+
-
bool OnBtnNewGameClicked(const CEGUI::EventArgs&);
+
-
 
+
-
bool OnBtnLoadGameClicked(const CEGUI::EventArgs&);
+
-
 
+
-
bool OnBtnSettingsClicked(const CEGUI::EventArgs&);
+
-
 
+
-
bool OnBtnExitClicked(const CEGUI::EventArgs&);
+
</pre>
</pre>
-
These are the window callback functions. Ehen the user will push a button on the cegui layout, the corresponding function will be called. Important, that all CEGUI callback function must foloww the following definition:
 
- 
-
<pre>bool MyCEGUIEventHandler(const CEGUI::EventArgs&);</pre>
 
 +
==Time stamps ==
 +
Current date and time is not so important in 3D apps, but a coll looking log file contents the starting time at least in a headline. We write the current date and time into string, using the _strdate and _strtime functions (you have to include "time.h" :
<pre>
<pre>
-
 
+
char dateStr [9];
-
iObjectRegistry* object_reg;
+
char timeStr [9];
-
 
+
_strdate( dateStr);
-
csEventID FinalProcess;
+
_strtime( timeStr );
-
+
-
csRef<iCEGUI> cegui;
+
-
 
+
-
csRef<EventHandler> eventHandler;
+
</pre>
</pre>
-
We need a pointer to the object registry, (to communicate with the CS framework), a refernce to cegui plugin and the event handler.
+
Ok, now we create a head line, using the date and time info:
-
 
+
-
== Implementing ''Initalize'' function ==
+
<pre>
<pre>
-
bool cimGuiHandler::Initialize(iObjectRegistry *obj_reg)
+
csString logStr("---------------------------------------");
-
{
+
logStr+="\n";
-
object_reg = obj_reg;
+
logStr+="Cim started at ";
-
eventHandler.AttachNew (new EventHandler (this));
+
logStr+=dateStr;
-
csRef<iEventQueue> queue = CS_QUERY_REGISTRY(object_reg, iEventQueue);
+
logStr+=" : ";
-
if (queue.IsValid())
+
logStr+=timeStr;
-
{
+
-
csEventID events[]=
+
-
{
+
-
csevPostProcess(object_reg),
+
-
CS_EVENTLIST_END
+
-
};
+
-
queue->RegisterListener(eventHandler,events);
+
csReporterHelper::Report(GetObjectRegistry(),CS_REPORTER_SEVERITY_NOTIFY,"cim",logStr.GetData());
}
}
- 
-
FinalProcess = csevPostProcess (object_reg);
 
</pre>
</pre>
-
TOur event handler will interesting for the Postprocess event. I described the sunscribing mechanism in the previous totorial.
+
Calling the csReporterHelper::Report (or the csReport macro) the head line goes to the log file.
-
<pre>
+
-
//init Cegui plugin
+
-
cegui = CS_QUERY_REGISTRY (object_reg,iCEGUI);
+
-
if (!cegui) return false;
+
-
if( !cegui->Initialize() ) return false;
+
-
</pre>
+
-
We query and start Cegui plugin. <br>
+
-
<pre>
+
-
cegui->GetLoggerPtr ()->setLoggingLevel(CEGUI::Informative);
+
-
cegui->GetSchemeManagerPtr ()->loadScheme("Falagard.scheme");
+
-
cegui->GetSystemPtr ()->setDefaultMouseCursor("Falagard", "MouseArrow");
+
-
CEGUI::Font* font = cegui->GetFontManagerPtr ()->createFont("FreeType",
+
-
"Vera", "/fonts/ttf/Vera.ttf");
+
-
font->setProperty("PointSize", "10");
+
-
font->load();
+
-
</pre>
+
-
CEGUI has a builtin logging system. We can choose the needed logging level from this enum:
+
That's it. See the code for all changes. Get the sources from [http://www.crystaldoc.atw.hu/src/cim/step4.zip here]
-
<pre>
+
-
enum LoggingLevel
+
-
{
+
-
Errors, //!< Only actual error conditions will be logged.
+
-
Standard, //!< Basic events will be logged (default level).
+
-
Informative, //!< Useful tracing (object creations etc) information will be logged.
+
-
Insane //!< Mostly everything gets logged (use for heavy tracing only, log WILL be big).
+
-
};
+
-
</pre>
+
-
 
+
-
Next we load our scheme file (that describes the skin of our windows), and we set up the mouse cursor. Cegui depends on freetype font, so we load a symphatic one (Vera.ttf).
+
-
 
+
-
== Callback functions ==
+
-
 
+
-
<pre>
+
-
//setup CEGUI callback functions
+
-
CEGUI::WindowManager* winMgr = cegui->GetWindowManagerPtr ();
+
-
 
+
-
// Load layout and set as root
+
-
cegui->GetSystemPtr ()->setGUISheet(winMgr->loadWindowLayout("cimmain.xml"));
+
-
 
+
-
//main window
+
-
CEGUI::Window* btn = winMgr->getWindow("BtnNewGame");
+
-
btn->subscribeEvent(CEGUI::PushButton::EventClicked,
+
-
CEGUI::Event::Subscriber(&cimGuiHandler::OnBtnNewGameClicked, this));
+
-
 
+
-
CEGUI::Window* btn = winMgr->getWindow("BtnLoadGame");
+
-
btn->subscribeEvent(CEGUI::PushButton::EventClicked,
+
-
CEGUI::Event::Subscriber(&cimGuiHandler::OnBtnLoadGameClicked, this));
+
-
 
+
-
CEGUI::Window* btn = winMgr->getWindow("BtnSettings");
+
-
btn->subscribeEvent(CEGUI::PushButton::EventClicked,
+
-
CEGUI::Event::Subscriber(&cimGuiHandler::OnBtnSettingsClicked, this));
+
-
 
+
-
CEGUI::Window* btn = winMgr->getWindow("BtnExit");
+
-
btn->subscribeEvent(CEGUI::PushButton::EventClicked,
+
-
CEGUI::Event::Subscriber(&cimGuiHandler::OnBtnExitClicked, this));
+
-
 
+
-
</pre>
+
-
 
+
-
 
+
-
The first version of the main menu will be something, like this:
+
-
 
+
-
[[Image:cim4_1.jpg]]
+
-
 
+
-
I created this "wonderful" interface with the Celayout editor. You can find this application on the cegui website.
+
-
 
+
-
Every button has an unique name. It's important, because the CEGUI windows manager will find our windows by name. This is the right way to subscrie to an CEGUI event:
+
-
 
+
-
CEGUI::Window* btn = winMgr->getWindow("BtnExit");
+
-
btn->subscribeEvent(CEGUI::PushButton::EventClicked,
+
-
CEGUI::Event::Subscriber(&cimGuiHandler::OnBtnExitClicked, this));
+
-
 
+
-
The ''OnBtnExitClicked'' function will be called, when he user clicks on the exit button (name ''BtnExit''). The function will add to the button real functionality.
+
-
 
+
-
== The event handler section ==
+
-
 
+
-
<pre>
+
-
bool cimGuiHandler::HandleEvent(iEvent &ev)
+
-
{
+
-
if (ev.Name == FinalProcess)
+
-
cegui->Render();
+
-
}
+
-
</pre>
+
-
This is easy. Just call the ''Render'' function to render CEGUI interface.
+
[[Tutorials|Tutorial Home]]

Revision as of 14:21, 20 July 2008

Contents

Step Four: : Setup the logging system

Introduction

The Crystal Space SDK contents a built-in reporter system. You can sending messages to the following places:

  • stdout : Your message will be sent to the standard output.
  • stderr : Your message will be sent to standard error channel.
  • alert  : Your message will be displayed in a information window.
  • console: Your message will be displayed on the console output.
  • debug  : Your massage will be logged into the debug log file.
  • popup  :

Adding some log-related config options

Let's create an optional log file. First, we add to our cim.cfg the following options:

Cim.Settings.EnableLogging = true; Cim.Settings.DebugFileName = /cim/debug.log Cim.Settings.AppendLogFile = false

When the EnableLogging option is true, the game writes the report messages in the log file. The DebugFileName decides the name of the log file. The AppendLogFile option controls, the app creates a new log file or appends the messages to the old one (if any).

Ok, let's go to load this options in the cimGame::LoadConfig(): 

bool cimGame::LoadConfig()
{
	csRef<iConfigManager> confman (CS_QUERY_REGISTRY (GetObjectRegistry(), iConfigManager));
	startmap = confman->GetStr("Cim.Settings.StartLevel","terrain");
	use_console = confman->GetBool("Cim.Settings.EnableConsole",false);
	enable_logging = confman->GetBool("Cim.Settings.EnableLogging",false);
	debug_filename = confman->GetStr("Cim.Settings.DebugFileName","/cim/debug.log");
	append_logfile = confman->GetBool("Cim.Settings.AppendLogFile",true);
	return true;
}


Listening the reports

Crystal Space provides us the iStandardReporterListener interface to do this. Let's query this: 

listener = CS_QUERY_REGISTRY(GetObjectRegistry(),iStandardReporterListener);

Ok, we have a the listener, let's customize it. As we said, Crystal Space ensures you many channel to your reports. Crystal Space uses 5 severity level:

  • CS_REPORTER_SEVERITY_BUG: his is the worst thing that can happen. It means that some code detected a bug in Crystal Space.
  • CS_REPORTER_SEVERITY_ERROR: There was an error of some kind. Usually this is an error while reading data.
  • CS_REPORTER_SEVERITY_WARNING: There was some condition which is non fatal but is suspicious.
  • CS_REPORTER_SEVERITY_NOTIFY: This is for debugging and it will usually generate an entry in some log.

We can define, on what messaging channel listening what severity levels. iStandardReporterLIstener has a SetMessageDestination function: 

virtual void SetMessageDestination (int severity,
  	bool do_stdout, bool do_stderr, bool do_console,
	bool do_alert, bool do_debug, bool do_popup = false) = 0;

We want to use the standard output, the console and the debug file. So the code is: 

listener->SetMessageDestination(CS_REPORTER_SEVERITY_ERROR,true,false,true,false,true,false);
	  listener->SetMessageDestination(CS_REPORTER_SEVERITY_WARNING,true,false,true,false,true,false);
	  listener->SetMessageDestination(CS_REPORTER_SEVERITY_NOTIFY,true,false,true,false,true,false);
	  listener->SetMessageDestination(CS_REPORTER_SEVERITY_DEBUG,true,false,true,false,true,false);

Now we set up the log filename: 

listener->SetDebugFile(debug_filename,append_logfile);

Time stamps

Current date and time is not so important in 3D apps, but a coll looking log file contents the starting time at least in a headline. We write the current date and time into string, using the _strdate and _strtime functions (you have to include "time.h" : 

char dateStr [9];
	  char timeStr [9];
	  _strdate( dateStr);
	  _strtime( timeStr );

Ok, now we create a head line, using the date and time info: 

csString logStr("---------------------------------------");
	  logStr+="\n";
	  logStr+="Cim started at ";
	  logStr+=dateStr;
	  logStr+=" : ";
	  logStr+=timeStr;

	  csReporterHelper::Report(GetObjectRegistry(),CS_REPORTER_SEVERITY_NOTIFY,"cim",logStr.GetData());
  }

Calling the csReporterHelper::Report (or the csReport macro) the head line goes to the log file.


That's it. See the code for all changes. Get the sources from here

Tutorial Home

Retrieved from "http://www.crystalspace3d.org/main/Cimstep4"
| Article | Discussion | View source | History |