Isomet Modular Synthesiser (iMS) API  v1.4.2
iMS API
Public Member Functions | List of all members
iMS::IEventHandler Class Reference

Interface Class for an Event Handler to be defined in User Code and subscribed to library events. More...

#include <include/IEventHandler.h>

Public Member Functions

 IEventHandler ()
 Default Constructor.
 
virtual ~IEventHandler ()
 Virtual Destructor.
 
bool operator== (const IEventHandler e)
 Used internally to identify Functions subscribed to Events. Not intended for Application usage. More...
 
Overrideable User Action on Event
virtual void EventAction (void *sender, const int message, const int param=0)
 This Method must be overriden by a User derived callback class. More...
 
virtual void EventAction (void *sender, const int message, const int param, const int param2)
 This Method must be overriden by a User derived callback class. More...
 
virtual void EventAction (void *sender, const int message, const double param)
 This Method must be overriden by a User derived callback class. More...
 
virtual void EventAction (void *sender, const int message, const int param, const std::vector< std::uint8_t > data)
 This Method must be overriden by a User derived callback class. More...
 

Detailed Description

Interface Class for an Event Handler to be defined in User Code and subscribed to library events.

Note that it is not possible to subscribe a single derived class to multiple events from different source objects in the library (as in a system-wide message handler) because the message enum integer values overlap each other. This is a conscious design choice to encourage encapsulation. A class may still be subscribed to multiple events as long as they are triggered from the same source object.

Example:

class ImageVerifySupervisor : public IEventHandler
{
private:
bool m_verifying{ true };
public:
void EventAction(void* sender, const int message, const int param)
{
switch (message)
{
case (ImageDownloadEvents::VERIFY_SUCCESS) : std::cout << "Image Verify Successful!" << std::endl; m_verifying = false; break;
case (ImageDownloadEvents::VERIFY_FAIL) : std::cout << "Image Verify FAILED!" << std::endl; m_verifying = false; break;
}
}
bool Busy() const { return m_verifying; };
};

The above code snippet defines a class "ImageVerifySupervisor" that inherits from the IEventHandler base class. This is used during the download of an Image to the Controller to determine whether the verification of the download was successful or not.

The class contains a private boolean variable which is initialised to true. It overrides the EventAction interface class method to do something when the VERIFY_SUCCESS and VERIFY_FAIL events are raised. User code can read the Busy() function to determine whether the downloader is still in the process of verifying the download or whether it has finished (which is assumed to be the case once either of the 2 events are received).

To use the class, the application code creates an ImageVerifySupervisor object at the same time as starting a verify on an ImageDownload. It then links the object to the ImageDownload by calling the Subscribe() method for both ImageDownloadEvents::VERIFY_SUCCESS and ImageDownloadEvents::VERIFY_FAIL, passing to the method the address of the ImageVerifySupervisor object as a function pointer.

ImageDownload * dl = new ImageDownload(ims, img);
ImageVerifySupervisor vs;
dl->ImageDownloadEventSubscribe(ImageDownloadEvents::VERIFY_SUCCESS, &vs);
dl->ImageDownloadEventSubscribe(ImageDownloadEvents::VERIFY_FAIL, &vs);
dl->StartVerify();
while (vs.Busy()) {
std::this_thread::sleep_for(std::chrono::milliseconds(50));
}
dl->ImageDownloadEventUnsubscribe(ImageDownloadEvents::VERIFY_SUCCESS, &vs);
dl->ImageDownloadEventUnsubscribe(ImageDownloadEvents::VERIFY_FAIL, &vs);
delete dl;

When the verify completes, it will trigger either the VERIFY_SUCCESS or VERIFY_FAIL events which, through the library's event handling mechanism, will identify the subscribed function and call the EventAction method.

Author
Dave Cowan
Date
2015-11-03
Since
1.0

Member Function Documentation

virtual void iMS::IEventHandler::EventAction ( void *  sender,
const int  message,
const int  param = 0 
)
virtual

This Method must be overriden by a User derived callback class.

When a user class derived from IEventHandler is subscribed to receive event notifications from the iMS Library, it is this function that is always called when the event is raised. Therefore it is essential to override this method to process the event and to do something with it.

This overloaded callback function provides integer parameter data to user code.

Parameters
[in]senderA pointer to the class that triggers the event callback. Can be used to obtain additional information.
[in]messagean integer that maps to an enum in the Events class associated with the callback subscription
[in]paraman optional integer parameter that provides additional information on the callback event.
Since
1.0
virtual void iMS::IEventHandler::EventAction ( void *  sender,
const int  message,
const int  param,
const int  param2 
)
virtual

This Method must be overriden by a User derived callback class.

When a user class derived from IEventHandler is subscribed to receive event notifications from the iMS Library, it is this function that is always called when the event is raised. Therefore it is essential to override this method to process the event and to do something with it.This overloaded callback function provides integer parameter data to user code.

Parameters
[in]senderA pointer to the class that triggers the event callback. Can be used to obtain additional information.
[in]messagean integer that maps to an enum in the Events class associated with the callback subscription
[in]paraman integer parameter that provides additional information on the callback event.
[in]param2an optional integer parameter that provides further additional information on the callback event.
Since
1.2
virtual void iMS::IEventHandler::EventAction ( void *  sender,
const int  message,
const double  param 
)
virtual

This Method must be overriden by a User derived callback class.

When a user class derived from IEventHandler is subscribed to receive event notifications from the iMS Library, it is this function that is always called when the event is raised. Therefore it is essential to override this method to process the event and to do something with it.

This overloaded callback function provides floating point parameter data to user code.

Parameters
[in]senderA pointer to the class that triggers the event callback. Can be used to obtain additional information.
[in]messagean integer that maps to an enum in the Events class associated with the callback subscription
[in]paraman floating point parameter that provides additional information on the callback event.
Since
1.1
virtual void iMS::IEventHandler::EventAction ( void *  sender,
const int  message,
const int  param,
const std::vector< std::uint8_t >  data 
)
virtual

This Method must be overriden by a User derived callback class.

When a user class derived from IEventHandler is subscribed to receive event notifications from the iMS Library, it is this function that is always called when the event is raised. Therefore it is essential to override this method to process the event and to do something with it.

This overloaded callback function provides a vector of byte data to user code.

Parameters
[in]senderA pointer to the class that triggers the event callback. Can be used to obtain additional information.
[in]messagean integer that maps to an enum in the Events class associated with the callback subscription
[in]paraman integer parameter that provides information on the callback event.
[in]dataa byte vector parameter that provides additional information on the callback event.
Since
1.2
bool iMS::IEventHandler::operator== ( const IEventHandler  e)

Used internally to identify Functions subscribed to Events. Not intended for Application usage.

Since
1.0

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