OP2Event

From OPU Wiki

All events are derived from 1 base-class called OP2Event.

All new event types are to be derived from OP2Event, and should be created using the _new keyword, and destroyed using _delete (both defined in _memory.h)

Every new event is added to an event-list. Derived events should call their ancestor's constructor when created, so the OP2Event constructor can perform this addition. Without it the newly created event will not be added to the event-queue, and will therefor never be executed.

Each event can have an ID assigned to it. Some events set this ID for you, where others can be supplied by the user, and changed later.

Table of contents

1 Properties 1.1 public: 1.2 private: 2 Constructor 3 Members 3.1 protected: 3.2 public:

Properties

The properties are simular to the ones used by the OP2 Trigger-system. I know i could have changed the NoRepeat into a more sensible property "Repeat" but i thought it be better to keep it the same as OP2, so it won't cause any mistakes when using the Events, where you've used Triggers before. For making your code more understandable, i've added the function Repeat( ) wich simply returns !NoRepeat.

IMPORTANT: although NoRepeat can be changed after the event was created, changing it from a 1-time event to an indefinate one will not always work! Example: if an event was set as 1-time, and you change NoRepeat after it has fired, it will not reset itself; it will be a dead event.

The whole OP2Event class is just 15 bytes long (including vftable), so it can be stored in a 16-byte aligned memory-model.

public:

type	name	description
int	ID	holds the IDentification number of this event
_callbackfunc	CallBackFunction	the callback-function

The ID number could either be supplied by the OP2Event class when the object is created, or it could be a public property, that can be set by the user. This differs per event. The base class OP2Event does upport a user-supplied ID number.

_callbackfunc is defined in OP2Event.h as:

void (*_callbackfunc)(OP2Event*);

This means, the CallBack function has access to the event that called it. This way it can access the class members, including the ID number of the event. Although this is an int, it is possible to assign a pointer (ANY pointer type) to this value upon event creation by using a type-cast. It could, for example, hold a simple identification of the event that caused the callback, or the ID-number of a unit, or group for which the event was created in the first place.

When deriving descendent classes, the callback function can typecast the OP2Event* param to the correct eventclass type.

private:

type	name	description
unsigned short	fired	counts times fired
unsigned char	flags	holds the event flags
	0000.0001	Enabled
	0000.0010	Repeat
	0000.0100	DeleteWhenFired
	0000.1000	FirstRun (used internally)
	0001.0000	Deleted (used internally)
	0010.0000	unused
	0100.0000	unused
	1000.0000	unused

The 3 (unused) MSB flag positions can be used by descendent classes. Do not let descendents change the 5 standard flags, but use the public setters instead: Enable/Disable/SetDeleteWhenFired (see below).

Constructor

name	description
OP2Event::OP2Event( )	do not call - use the CreateOP2Event function instead (see below)

OP2Event *CreateOP2Event(bool enable,bool norepeat,_callbackfunc callback,int id)

CreateOP2Event creates an instance of the OP2Event class in the SAVE memory segment, and initializes it. Do not call the constructor directly! This creator will also add the new event to the main EventList.

Members

protected:

name	description
void DoCallBack( )	is to be called whenever the event triggers
virtual void EventFunction( )	should contain the event checking code. If an event is to be triggered it should call DoCallBack. Do not call the CallBackFunction directly. DoCallBack does some other things (including an increase of HasFired)

public:

name	description
void Destroy( )	removes the event from the EventList, and deletes itself from memory
void Enable( )	enables the event
void Disable( )	disables the event
void SetDeleteWhenFired(int set)	use this in combination with 1-time events

When SetDeleteWhenFired is set to 1 the event is removed from the main EventList, and gets deleted from memory. Its allocated space being marked as free. You can no longer access the event after it has fired. This has no effect on repetative events. This option is on by default for one-time events. If you need to access the event after it has been fired, turn the option off. This can be done along with the creation:

CreateTimerEvent(1,1,500,TimerFired)->SetDeleteWhenFired(0);

name	description
bool IsInitialized( )	returns true if the event exists, and is added to the EventList
int HasFired( )	returns the number of times this event has fired
bool Repeat( )	returns true is this is a repetative event
bool Enabled( )	returns true when the event is enabled