#include <Component.h>

Description

Class that extends the functionality of an Entity, but as a removable and addable object.

To work, all Component s have hosts; when a host updates, all components do as well. Like Entities, Components can have a Draw and a Step function with an overloadable OnStep / OnDraw. In addition, all Component's also have event handling capabilities. Setable with strings, it is possible to maintain and assign functions to run on certain events and even define your own events for custom Components.

Using Events

When making your own Components, you will typically also want to include your own custom events. InstallEvent() is the protected function that adds a new recognized event with the given name. Once installed, EmitEvent() should be called at the appropriate time user functions should be run.

Any component is aware of at least 2 events: on-attach, called when a component is bound to its host. and on-detach, right before the removal sequence is started for a host.

Functions
std::string	GetTag ()

Entity *	GetHost () const

template<typename T >
T *	GetHostAs () const

Entity::ID	GetHostID () const

virtual std::string	GetInfo ()

Protected Member Functions
virtual void	OnStep ()

virtual void	OnDraw ()

virtual void	OnAttach ()

void	InstallEvent (const std::string &eventName, EventHandler mainHandler=nullptr, void *data=nullptr)

void	UninstallEvent (const std::string &)

Event control
Events allow for an efficient option to have logic run in reaction to a trigger. When construction your own Component, you can install any number of Events and call EmitEvent() when you'd like the user's logic to run.
using	EventHandler = bool()(void , Component *component, Entity::ID self, Entity::ID source, const std::vector< std::string > &args)

bool	EmitEvent (const std::string &eventName, Entity::ID source=Entity::ID(), const std::vector< std::string > &args={})

bool	CanHandleEvent (const std::string &eventName)

void	InstallHook (const std::string &eventName, EventHandler, void *data=nullptr)

void	UninstallHook (const std::string &eventName, EventHandler)

void	InstallHandler (const std::string &eventName, EventHandler, void *data=nullptr)

void	UninstallHandler (const std::string &eventName, EventHandler)

std::vector< std::string >	GetKnownEvents () const

Member Typedef Documentation

using EventHandler = bool (*)(void *, Component * component, Entity::ID self, Entity::ID source, const std::vector<std::string> & args)

A handler for an event.

The return value tells the event system to propogate the event thats currently being processed.

Member Function Documentation

std::string GetTag ( )

inline

Returns a string identifier belonging to the component. Each component implementation should have a unique name.

Entity* GetHost ( ) const

inline

Returns the set host of the component. If no host is set, nullptr is returned.

T* GetHostAs ( ) const

inline

Convenience function. Equivalent to dynamic_cast<T*>(GetHost())

Entity::ID GetHostID ( ) const

inline

Returns a ID of the host.

virtual std::string GetInfo ( )

inlinevirtual

Returns a string containing human-readable information on the state of the component.

Reimplemented in Mutator, Object2D, StateControl, GUI, Text2D, Shape2D, RenderMesh, Clock, RenderLight, and Scheduler.

bool EmitEvent	(	const std::string &	eventName,
		Entity::ID	source = `Entity::ID()`,
		const std::vector< std::string > &	args = `{}`
	)

Triggers the specified event for this EventSystem.

Returns whether the event was allowed to propogate all the way to the main handler (in other words, lets you know whether all the handlers allowed the event to happen) Source is passed to the handler and is usually the source of the event (but does not have to be)

Parameters

eventName	Name of the event. This should match the name that was installed.
source	Optional ID that indicates the source of the event. For example, in a collision, this may be the object collided with.
args	Optional string vector with additional information to be used by the event.

bool CanHandleEvent ( const std::string & eventName )

Returns whether there exists at least one handler for the given event.

void InstallHook	(	const std::string &	eventName,
		EventHandler	,
		void *	data = `nullptr`
	)

Adds a hook to the event.

A hook happens at the end of a given event after all the handlers have been run. Hooks occur regardless of event handler propogation. (the return value is ignored for all hooks)

void UninstallHook	(	const std::string &	eventName,
		EventHandler
	)

Removes a hook added with InstallHook()

void InstallHandler	(	const std::string &	eventName,
		EventHandler	,
		void *	data = `nullptr`
	)

Adds a handler to an event.

Handlers that are added are run in LIFO order and their return values dictate whether the event should propogate. the last handler run for an event is always the main handler of the event.

void UninstallHandler	(	const std::string &	eventName,
		EventHandler
	)

Removes a handler added with InstallHandler()

std::vector<std::string> GetKnownEvents ( ) const

Returns a list of event names that this eventsystem is able to process

virtual void OnStep ( )

inlineprotectedvirtual

Function that is called upon each Run iteration. Component Run()s are run before the entity's run function.

Reimplemented in Mutator, StateControl, GUI, and Scheduler.

virtual void OnDraw ( )

inlineprotectedvirtual

Function that is called upon each Draw iteration. Component Draw()s are run before the entity's draw function.

Reimplemented in StateControl, Text2D, Shape2D, RenderMesh, and RenderLight.

virtual void OnAttach ( )

inlineprotectedvirtual

Function that is called upon a host entity's Attach() function calling. It is run right after the host is set.

Reimplemented in Object2D.

void InstallEvent	(	const std::string &	eventName,
		EventHandler	mainHandler = `nullptr`,
		void *	data = `nullptr`
	)

protected

Adds a new event to be recognized by the EventSystem.

if mainHandler is nullptr, the event is still added, but has no default handler is set. The default handler is always guaranteed to run first for the event.

void UninstallEvent ( const std::string & )

protected

removes a handler of an event

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

/home/jc/git/Dynacoe/DynacoeSrc/includes/Dynacoe/Component.h

Description

Using Events

Functions

Protected Member Functions

Event control

Member Typedef Documentation

Member Function Documentation