stmi::BasicDeviceManager Class Reference

Helper class for implementing a device manager. More...

Inheritance diagram for stmi::BasicDeviceManager:

Classes
class	ListenerData
	Helper class that represents a listener. More...
class	ListenerExtraData
	Base class to store extra listener data. More...

Public Member Functions
shared_ptr< Device >	getDevice (int32_t nDeviceId) const noexcept override
	Returns the device with the given id, or null if not found. More...
std::vector< int32_t >	getDevicesWithCapabilityClass (const Capability::Class &oCapabilityClass) const noexcept override
	Returns the ids of the devices that have the given capability class. More...
std::vector< int32_t >	getDevices () const noexcept override
	Returns the ids of all the device manager's devices. More...
std::vector< Capability::Class >	getCapabilityClasses () const noexcept override
	The registered capability classes of the device manager. More...
std::vector< Capability::Class >	getDeviceCapabilityClasses () const noexcept override
	The registered capability classes of the device manager's devices. More...
std::vector< Event::Class >	getEventClasses () const noexcept override
	The registered event classes the device manager and all its devices can send. More...
bool	isEventClassEnabled (const Event::Class &oEventClass) const noexcept override
	Tells whether an event class is enabled. More...
void	enableEventClass (const Event::Class &oEventClass) noexcept override
	Enables an event class. More...
bool	addAccessor (const shared_ptr< Accessor > &) noexcept override
	Default empty implementation. More...
bool	removeAccessor (const shared_ptr< Accessor > &) noexcept override
	Default empty implementation. More...
bool	hasAccessor (const shared_ptr< Accessor > &) noexcept override
	Default empty implementation. More...
bool	addEventListener (const shared_ptr< EventListener > &refEventListener, const shared_ptr< CallIf > &refCallIf) noexcept override
	Adds an event listener with its callif condition to the device manager. More...
bool	addEventListener (const shared_ptr< EventListener > &refEventListener) noexcept override
	Adds an event listener to the device manager. More...
bool	removeEventListener (const shared_ptr< EventListener > &refEventListener, bool bFinalize) noexcept override
	Removes an event listener from the device manager. More...
bool	removeEventListener (const shared_ptr< EventListener > &refEventListener) noexcept override
	Removes an event listener from the device manager. More...
Public Member Functions inherited from stmi::ChildDeviceManager
shared_ptr< ParentDeviceManager >	getParent () const noexcept
	Gets the parent of this child device manager. More...
shared_ptr< ParentDeviceManager >	getParent () noexcept
	Gets the parent of this child device manager. More...
shared_ptr< ParentDeviceManager >	getRoot () const noexcept
	Returns the root device manager. More...
shared_ptr< ParentDeviceManager >	getRoot () noexcept
	Returns the root device manager. More...
bool	isParent () const noexcept
	Tells whether this instance is also a ParentDeviceManager. More...
shared_ptr< ParentDeviceManager >	getAsParent () const noexcept
	If a parent returns this object as a parent. More...
shared_ptr< ParentDeviceManager >	getAsParent () noexcept
	If a parent returns this object as a parent. More...
Public Member Functions inherited from stmi::DeviceManager
virtual	~DeviceManager () noexcept=default
template<typename TCapa >
bool	getCapability (shared_ptr< TCapa > &refCapa) const noexcept
	Request a registered device manager capability. More...
virtual shared_ptr< Capability >	getCapability (const Capability::Class &oClass) const noexcept=0
	Requests the instance of a capability class. More...
virtual shared_ptr< Capability >	getCapability (int32_t nCapabilityId) const noexcept=0
	Returns the device manager's capability with the given id, or null if not found. More...

Protected Member Functions
	BasicDeviceManager (const std::vector< Capability::Class > &aCapabitityClasses, const std::vector< Capability::Class > &aDeviceCapabitityClasses, const std::vector< Event::Class > &aEventClasses, bool bEnableEventClasses, const std::vector< Event::Class > &aEnDisableEventClasses) noexcept
	Constructor. More...
bool	addDevice (const shared_ptr< Device > &refDevice) noexcept
	Adding a device. More...
bool	removeDevice (const shared_ptr< Device > &refDevice) noexcept
	Removing a device. More...
bool	isWithinAListenerCallback () const noexcept
	Tells whether the caller is within a listener callback. More...
virtual void	finalizeListener (ListenerData &oListenerData) noexcept=0
	Finalize listener. More...
shared_ptr< const std::list< ListenerData *> >	getListeners () noexcept
	Returns the listeners data pointers. More...
int32_t	getEventClassIndex (const Event::Class &oEventClass) const noexcept
	Returns the index of the event class in the array passed to the constructor. More...
void	resetExtraDataOfAllListeners () noexcept
	Calls overloaded ListenerExtraData::reset() for each listener. More...
Protected Member Functions inherited from stmi::ChildDeviceManager
	ChildDeviceManager () noexcept
	Constructor. More...
Protected Member Functions inherited from stmi::DeviceManager
	DeviceManager () noexcept

Static Protected Member Functions
static uint64_t	getUniqueTimeStamp () noexcept
	Returns a unique time stamp. More...

Additional Inherited Members
Static Public Member Functions inherited from stmi::DeviceManager
static int64_t	getNowTimeMicroseconds () noexcept
	Current time from epoch in microseconds. More...

Detailed Description

Helper class for implementing a device manager.

Constructor & Destructor Documentation

BasicDeviceManager()

stmi::BasicDeviceManager::BasicDeviceManager ( const std::vector< Capability::Class > &  aCapabitityClasses, const std::vector< Capability::Class > &  aDeviceCapabitityClasses, const std::vector< Event::Class > &  aEventClasses, bool  bEnableEventClasses, const std::vector< Event::Class > &  aEnDisableEventClasses  )

protectednoexcept

Constructor.

If bEnableEventClasses is true then all event classes in aEnDisableEventClasses are enabled, all others disabled, if false then all event classes supported by this instance are enabled except those in aEnDisableEventClasses. BasicDeviceManager doesn't allow disabling event classes once constructed, only enabling. Example: To enable all the event classes supported by this instance pass

bEnableEventClasses = false,  aEnDisableEventClasses = {}

Parameters

aCapabitityClasses	Vector of registered device manager capability classes supported by this manager.
aDeviceCapabitityClasses	Vector of registered device capability classes supported by this manager.
aEventClasses	Vector of registered event classes supported by this manager.
bEnableEventClasses	Whether to enable or disable all but aEnDisableEventClasses.
aEnDisableEventClasses	The event classes to be enabled or disabled according to bEnableEventClasses.

Member Function Documentation

addAccessor()

bool stmi::BasicDeviceManager::addAccessor ( const shared_ptr< Accessor > &  )

inlineoverridevirtualnoexcept

Default empty implementation.

Returns

false

Implements stmi::DeviceManager.

addDevice()

bool stmi::BasicDeviceManager::addDevice ( const shared_ptr< Device > &  refDevice )

protectednoexcept

Adding a device.

Subclasses of BasicDeviceManager should call this when adding a device. If the device couldn't be added (for example because it already is) false is returned.

Parameters

refDevice

The device to be added. Cannot be null.

Returns

Whether the device could be added.

addEventListener() [1/2]

bool stmi::BasicDeviceManager::addEventListener ( const shared_ptr< EventListener > &  refEventListener, const shared_ptr< CallIf > &  refCallIf  )

overridevirtualnoexcept

Adds an event listener with its callif condition to the device manager.

The EventListener callback function (actually its address) identifies the listener being added and is therefore used to remove it with removeEventListener(). The callback function is called for all events originating from this device manager's devices that satisfy the callif condition.

If the listener was already added, even with a different callif, the function has no effect and false is returned.

The device manager keeps a weak reference (std::weak_ptr) to the listener. This means that the caller has to keep a strong reference to the listener, otherwise it will be removed automatically.

A null callback condition refCallIf means that the callback function is called for all events. The device manager keeps a strong reference to the callif object as long as the listener remains in the device manager.

The event parameter passed to the callback function can be queued (outlive the callback) or modified if its interface allows it. To get the registered class of the event use Event::getEventClass() and statically cast to it. Note: don't use typeid(*refEvent) since it isn't necessarily equal to refEvent->getEventClass().getTypeInfo().

See also

class Event.

Example:

void createListeners()
    ...
    // The listener has to be stored in a member variable otherwise it will
    // automatically be removed from the device manager.
    m_refKeyEventListener = std::make_shared<stmi::EventListener>(
        [this](const shared_ptr<stmi::Event>& refEvent)
        {
            // Because of the callif condition below we know that refEvent
            // is a stmi::KeyEvent
            auto pKeyEvent = static_cast<stmi::KeyEvent*>(refEvent.get());
            ...
        });
    m_refDeviceManager->addEventListener(m_refKeyEventListener
                      , std::make_shared<stmi::CallIfEventClass>(typeid(stmi::KeyEvent)));
    ...
}

Parameters

refEventListener	The listener to be added. Cannot be null.
refCallIf	The callif condition to call back the listener. Can be null.

Returns

Whether the listener was added.

Implements stmi::DeviceManager.

addEventListener() [2/2]

bool stmi::BasicDeviceManager::addEventListener ( const shared_ptr< EventListener > &  refEventListener )

overridevirtualnoexcept

Adds an event listener to the device manager.

Shortcut of addEventListener(refEventListener, shared_ptr<CallIf>{}).

Parameters

refEventListener

The listener to be added. Cannot be null.

Returns

Whether the listener was added.

Implements stmi::DeviceManager.

enableEventClass()

void stmi::BasicDeviceManager::enableEventClass ( const Event::Class &  oEventClass )

overridevirtualnoexcept

Enables an event class.

See also

isEventClassEnabled(const Event::Class&)

Parameters

oEventClass

The event class to enable.

Implements stmi::DeviceManager.

finalizeListener()

virtual void stmi::BasicDeviceManager::finalizeListener ( ListenerData &  oListenerData )

protectedpure virtualnoexcept

Finalize listener.

This function is optionally called by this class when a listener is about to be removed. Subclasses should implement it by sending (if the listener's callif allows it) "cancels" for pressed keys, pressed mouse buttons, unclosed touch sequences, etc.

Parameters

oListenerData

Interface to call the listener's callback.

Implemented in stmi::testing::FakeDeviceManager.

getCapabilityClasses()

std::vector<Capability::Class> stmi::BasicDeviceManager::getCapabilityClasses ( ) const

overridevirtualnoexcept

The registered capability classes of the device manager.

Example: the vector {DeviceMgmtCapability::getClass()} is returned.

Returns

The set of registered device manager capability classes.

Implements stmi::DeviceManager.

getDevice()

shared_ptr<Device> stmi::BasicDeviceManager::getDevice ( int32_t  nDeviceId ) const

overridevirtualnoexcept

Returns the device with the given id, or null if not found.

Implements stmi::DeviceManager.

getDeviceCapabilityClasses()

std::vector<Capability::Class> stmi::BasicDeviceManager::getDeviceCapabilityClasses ( ) const

overridevirtualnoexcept

The registered capability classes of the device manager's devices.

The capability classes include those that managed devices potentially have, independently from the currently available devices.

Example: a device manager that handles mice and touch pads will return {PointerCapability::getClass(), TouchCapability::getClass()} even though no touch device is connected.

Returns

The set of registered device capability classes.

Implements stmi::DeviceManager.

getDevices()

std::vector<int32_t> stmi::BasicDeviceManager::getDevices ( ) const

overridevirtualnoexcept

Returns the ids of all the device manager's devices.

Returns

The set of device ids.

Implements stmi::DeviceManager.

getDevicesWithCapabilityClass()

std::vector<int32_t> stmi::BasicDeviceManager::getDevicesWithCapabilityClass ( const Capability::Class &  oCapabilityClass ) const

overridevirtualnoexcept

Returns the ids of the devices that have the given capability class.

Parameters

oCapabilityClass

The registered capability class.

Returns

The set of device ids.

Implements stmi::DeviceManager.

getEventClasses()

std::vector<Event::Class> stmi::BasicDeviceManager::getEventClasses ( ) const

overridevirtualnoexcept

The registered event classes the device manager and all its devices can send.

The event classes include those that managed devices potentially can send, independently from the currently available devices.

Returns

The set of registered event classes.

Implements stmi::DeviceManager.

getEventClassIndex()

int32_t stmi::BasicDeviceManager::getEventClassIndex ( const Event::Class &  oEventClass ) const

protectednoexcept

Returns the index of the event class in the array passed to the constructor.

The index can be used by ListenerData::handleEventCallIf(int32_t, const shared_ptr<Event>&, const shared_ptr<const Accessor>&) const for faster access to the simplified callif expression for the event class. This function can be called from the constructor of a subclass to initialize variables but has to be called after the call of this class' constructor.

Parameters

oEventClass

The class.

Returns

Index or -1 if not supported event class.

getListeners()

shared_ptr< const std::list< ListenerData* > > stmi::BasicDeviceManager::getListeners ( )

protectednoexcept

Returns the listeners data pointers.

The returned value prevents the data pointed to by the elements of the list to be deleted while the std::shared_ptr is held. This also means that BasicDeviceManager subclasses shouldn't store the shared_ptr because it would prevent deletion of unused ListenerData objects.

Returns

The reference counted pointer to the list.

getUniqueTimeStamp()

static uint64_t stmi::BasicDeviceManager::getUniqueTimeStamp ( )

inlinestaticprotectednoexcept

Returns a unique time stamp.

Allows to order events without relying on microseconds which isn't precise enough. The returned stamp increases after each call.

Returns

The unique timestamp (> 0).

hasAccessor()

bool stmi::BasicDeviceManager::hasAccessor ( const shared_ptr< Accessor > &  )

inlineoverridevirtualnoexcept

Default empty implementation.

Returns

false

Implements stmi::DeviceManager.

isEventClassEnabled()

bool stmi::BasicDeviceManager::isEventClassEnabled ( const Event::Class &  oEventClass ) const

overridevirtualnoexcept

Tells whether an event class is enabled.

If an event class is disabled the device manager (with all its devices) won't send events of that class to listeners.

Parameters

oEventClass

The registered event class.

Returns

Tells whether the event class is enabled.

Implements stmi::DeviceManager.

isWithinAListenerCallback()

bool stmi::BasicDeviceManager::isWithinAListenerCallback ( ) const

inlineprotectednoexcept

Tells whether the caller is within a listener callback.

removeAccessor()

bool stmi::BasicDeviceManager::removeAccessor ( const shared_ptr< Accessor > &  )

inlineoverridevirtualnoexcept

Default empty implementation.

Returns

false

Implements stmi::DeviceManager.

removeDevice()

bool stmi::BasicDeviceManager::removeDevice ( const shared_ptr< Device > &  refDevice )

protectednoexcept

Removing a device.

Subclasses of BasicDeviceManager should call this when removing a device. If the device couldn't be removed (for example because it isn't present) false is returned.

Parameters

refDevice

The device to be removed. Cannot be null.

Returns

Whether the device could be removed.

removeEventListener() [1/2]

bool stmi::BasicDeviceManager::removeEventListener ( const shared_ptr< EventListener > &  refEventListener, bool  bFinalize  )

overridevirtualnoexcept

Removes an event listener from the device manager.

If the listener wasn't found, false is returned, true otherwise. To be found the event listener must have been added with addEventListener() and not deleted since then. Beware! A copy of the event listener can't be used to remove it.

Optionally finalization events are sent to the listener before its removal. Example: if a device's key is pressed when this function is called, a RELEASE_CANCEL event is sent to the listener being removed.

Parameters

refEventListener	The listener to remove. Cannot be null.
bFinalize	Whether to send closing events to the listener.

Returns

Whether listener was removed.

Implements stmi::DeviceManager.

removeEventListener() [2/2]

bool stmi::BasicDeviceManager::removeEventListener ( const shared_ptr< EventListener > &  refEventListener )

overridevirtualnoexcept

Removes an event listener from the device manager.

Shortcut of removeEventListener(refEventListener, false).

Parameters

refEventListener

The listener to remove. Cannot be null.

Implements stmi::DeviceManager.

resetExtraDataOfAllListeners()

void stmi::BasicDeviceManager::resetExtraDataOfAllListeners ( )

protectednoexcept

Calls overloaded ListenerExtraData::reset() for each listener.