ParaEngine::CEventsCenter Class Reference

a global pool for user registered custom events. More...

#include <EventsCenter.h>

Public Member Functions
void	Reset ()
	remove all pending event from queue and clear all event listener
void	RegisterEvent (const string &sID, const string &sScript)
	register a mouse or key event handler More...
void	RegisterEvent (DWORD nEventType, const string &sID, const string &sScript)
	same as above RegisterEvent(), except that it allows caller to explicitly specify the event type, instead of deriving it from the event name. More...
void	AddEventHandler (CEventHandler *pEventHandler)
	add a given event handler. More...
void	UnregisterEvent (const string &sID)
	unregister a mouse or key event handler
void	UnregisterAllEvent ()
	unregister all mouse or key event handler
int	FireEvent (const IEvent &e)
	Fire mouse events, call all of its handler scripts with sCode immediately. More...
bool	PostEvent (const Event &e, bool bUnique=true)
	Post a event to the unhandled event pool, and return immediately. More...
void	FireAllUnhandledEvents ()
	fire all events in the unhandled events pool. More...

Static Public Member Functions
static CEventsCenter *	GetInstance ()

Detailed Description

a global pool for user registered custom events.

see events page for information about events parameters in scripting interface. events are categorized by types, see PE_types.h, events_def.h. There are also some predefined events in Predefinedevents.h.

Global ParaEngine event handlers are exposed through scripting interface, API interface, and managed API interface. Managed API interface are exposed as multi-cast delegate in the EventCenter class of ParaEngineManaged class.

Two types of event firing are supported: (1) Fire event immediately, similar to SendMessage in Win32 (2) Pose Event, which return immediate without executing the event handlers. similar to PostMessages in Win32 Since event raisers and event handlers may be in the same thread, PoseEvent is there to prevent interlocking of program code.

Example: SelectionToolWindow in ParaIDE are implemented through the new managed event handling interface. Whenever the game engine changes selection, the plug-in interface will receive an event, and in the event handler, it will update the GUI to reflect the recent changes in selection.

Member Function Documentation

AddEventHandler()

void CEventsCenter::AddEventHandler

(

CEventHandler *

pEventHandler

)

add a given event handler.

Parameters

pEventHandler

must be created using the default new operator. The caller does not need to delete it. The event center will have it deleted automatically.

FireAllUnhandledEvents()

void CEventsCenter::FireAllUnhandledEvents

(

)

fire all events in the unhandled events pool.

This function is called automatically during each frame move.

FireEvent()

int CEventsCenter::FireEvent

(

const IEvent &

e

)

Fire mouse events, call all of its handler scripts with sCode immediately.

this function will return when all events have been handled. use PoseEvents(), if one wants to return without calling their handlers; [Not thread safe]: this function must be called within the main thread.

Note

: default script event handler only insert a message to the NPL message queue and return immediately, so the actual handling of events will be delayed actually.

Parameters

e	event parameters

Returns

number of handlers called.

GetInstance()

CEventsCenter * CEventsCenter::GetInstance ( )

static

Returns

the singleton instance.

PostEvent()

bool CEventsCenter::PostEvent	(	const Event &	e,
		bool	bUnique = true
	)

Post a event to the unhandled event pool, and return immediately.

Events in unhandled event pool are handled during the next frame move. [Thread Safe]: this function is thread safe, since it will queue all events and call them in the main thread in the next frame move.

Parameters

e	: the input event
bUnique	if true, the event id is unique in the event pool, unless the ID is -1. If one tries to insert the event with the same id multiple times within a frame move, only the first one will be fired during each frame move.

Returns

RegisterEvent() [1/2]

void CEventsCenter::RegisterEvent	(	const string &	sID,
		const string &	sScript
	)

register a mouse or key event handler

Parameters

sID

a string identifier of the event handler. if sID begins with "_m" it is treated as a mouse click event, except that if sID begins with "_mm" it is treated as a mouse move event. if sID begins with "_md" it is treated as a mouse down event. if sID begins with "_mu" it is treated as a mouse up event. if sID begins with "_k" it is treated as a key down event. if sID begins with "_ku" it is treated as a key up event. if sID begins with "_n" it is treated as a network event handler.

sScript

the script to be executed when the event is triggered.This is usually a function call in NPL. sScript should be in the following format "{NPL filename};{sCode};". this is the same format in the UI event handler

RegisterEvent() [2/2]

void CEventsCenter::RegisterEvent	(	DWORD	nEventType,
		const string &	sID,
		const string &	sScript
	)

same as above RegisterEvent(), except that it allows caller to explicitly specify the event type, instead of deriving it from the event name.

Parameters

nEventType	any bit combination of EventHandler_type
sID	any unique string identifier
sScript	the NPL script.

---

The documentation for this class was generated from the following files:

• Client/trunk/ParaEngineClient/Core/EventsCenter.h
• Client/trunk/ParaEngineClient/Core/EventsCenter.cpp