Button map interface to translate between the driver's raw button/hat/axis elements and physical joystick features. More...

#include <IButtonMap.h>

Inheritance diagram for KODI::JOYSTICK::IButtonMap:

Public Member Functions
virtual	~IButtonMap ()=default

virtual std::string	ControllerID (void) const =0
	The add-on ID of the game controller associated with this button map.

virtual std::string	Location (void) const =0
	The Location of the peripheral associated with this button map.

virtual bool	Load (void)=0
	Load the button map into memory.

virtual void	Reset (void)=0
	Reset the button map to its defaults, or clear button map if no defaults.

virtual bool	IsEmpty (void) const =0
	Check if the button map is empty.

virtual std::string	GetAppearance () const =0
	Get the ID of the controller profile that best represents the appearance of the peripheral.

virtual bool	SetAppearance (const std::string &controllerId) const =0
	Set the ID of the controller that best represents the appearance of the peripheral.

virtual bool	GetFeature (const CDriverPrimitive &primitive, FeatureName &feature)=0
	Get the feature associated with a driver primitive.

virtual FEATURE_TYPE	GetFeatureType (const FeatureName &feature)=0
	Get the type of the feature for the given name.

virtual bool	GetScalar (const FeatureName &feature, CDriverPrimitive &primitive)=0
	Get the driver primitive for a scalar feature.

virtual void	AddScalar (const FeatureName &feature, const CDriverPrimitive &primitive)=0
	Add or update a scalar feature.

virtual bool	GetAnalogStick (const FeatureName &feature, ANALOG_STICK_DIRECTION direction, CDriverPrimitive &primitive)=0
	Get an analog stick direction from the button map.

virtual void	AddAnalogStick (const FeatureName &feature, ANALOG_STICK_DIRECTION direction, const CDriverPrimitive &primitive)=0
	Add or update an analog stick direction.

virtual bool	GetRelativePointer (const FeatureName &feature, RELATIVE_POINTER_DIRECTION direction, CDriverPrimitive &primitive)=0
	Get a relative pointer direction from the button map.

virtual void	AddRelativePointer (const FeatureName &feature, RELATIVE_POINTER_DIRECTION direction, const CDriverPrimitive &primitive)=0
	Add or update a relative pointer direction.

virtual bool	GetAccelerometer (const FeatureName &feature, CDriverPrimitive &positiveX, CDriverPrimitive &positiveY, CDriverPrimitive &positiveZ)=0
	Get an accelerometer from the button map.

virtual void	AddAccelerometer (const FeatureName &feature, const CDriverPrimitive &positiveX, const CDriverPrimitive &positiveY, const CDriverPrimitive &positiveZ)=0
	Get or update an accelerometer.

virtual bool	GetWheel (const FeatureName &feature, WHEEL_DIRECTION direction, CDriverPrimitive &primitive)=0
	Get a wheel direction from the button map.

virtual void	AddWheel (const FeatureName &feature, WHEEL_DIRECTION direction, const CDriverPrimitive &primitive)=0
	Add or update a wheel direction.

virtual bool	GetThrottle (const FeatureName &feature, THROTTLE_DIRECTION direction, CDriverPrimitive &primitive)=0
	Get a throttle direction from the button map.

virtual void	AddThrottle (const FeatureName &feature, THROTTLE_DIRECTION direction, const CDriverPrimitive &primitive)=0
	Add or update a throttle direction.

virtual bool	GetKey (const FeatureName &feature, CDriverPrimitive &primitive)=0
	Get the driver primitive for a keyboard key.

virtual void	AddKey (const FeatureName &feature, const CDriverPrimitive &primitive)=0
	Add or update a key.

virtual void	SetIgnoredPrimitives (const std::vector< CDriverPrimitive > &primitives)=0
	Set a list of driver primitives to be ignored.

virtual bool	IsIgnored (const CDriverPrimitive &primitive)=0
	Check if a primitive is in the list of primitives to be ignored.

virtual bool	GetAxisProperties (unsigned int axisIndex, int &center, unsigned int &range)=0
	Get the properties of an axis.

virtual void	SaveButtonMap ()=0
	Save the button map.

virtual void	RevertButtonMap ()=0
	Revert changes to the button map since the last time it was loaded or committed to disk.

Detailed Description

Button map interface to translate between the driver's raw button/hat/axis elements and physical joystick features.

See also: IButtonMapper

Constructor & Destructor Documentation

◆ ~IButtonMap()

virtual KODI::JOYSTICK::IButtonMap::~IButtonMap ( )

virtualdefault

Member Function Documentation

◆ AddAccelerometer()

virtual void KODI::JOYSTICK::IButtonMap::AddAccelerometer	(	const FeatureName &	feature,
		const CDriverPrimitive &	positiveX,
		const CDriverPrimitive &	positiveY,
		const CDriverPrimitive &	positiveZ )

pure virtual

Get or update an accelerometer.

Parameters

feature	Must be an accelerometer or this will return false
positiveX	The semiaxis corresponding to the positive X direction
positiveY	The semiaxis corresponding to the positive Y direction
positiveZ	The semiaxis corresponding to the positive Z direction

The driver primitives must be mapped to a semiaxis or this function will fail.

Returns: True if the accelerometer was updated, false if unchanged or failure occurred

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ AddAnalogStick()

virtual void KODI::JOYSTICK::IButtonMap::AddAnalogStick	(	const FeatureName &	feature,
		ANALOG_STICK_DIRECTION	direction,
		const CDriverPrimitive &	primitive )

pure virtual

Add or update an analog stick direction.

Parameters

feature	Must be an analog stick or this will return false
direction	The direction being mapped
primitive	The driver primitive for the specified analog stick and direction

Returns: True if the analog stick was updated, false otherwise

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ AddKey()

virtual void KODI::JOYSTICK::IButtonMap::AddKey	(	const FeatureName &	feature,
		const CDriverPrimitive &	primitive )

pure virtual

Add or update a key.

Parameters

feature	Must be a key
primitive	The feature's driver primitive

Returns: True if the feature was updated, false if the feature is unchanged or failure occurs

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ AddRelativePointer()

virtual void KODI::JOYSTICK::IButtonMap::AddRelativePointer	(	const FeatureName &	feature,
		RELATIVE_POINTER_DIRECTION	direction,
		const CDriverPrimitive &	primitive )

pure virtual

Add or update a relative pointer direction.

Parameters

feature	Must be a relative pointer or this will return false
direction	The direction being mapped
primitive	The driver primitive for the specified analog stick and direction

Returns: True if the analog stick was updated, false otherwise

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ AddScalar()

virtual void KODI::JOYSTICK::IButtonMap::AddScalar	(	const FeatureName &	feature,
		const CDriverPrimitive &	primitive )

pure virtual

Add or update a scalar feature.

Parameters

feature	Must be a scalar feature
primitive	The feature's driver primitive

Returns: True if the feature was updated, false if the feature is unchanged or failure occurs

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ AddThrottle()

virtual void KODI::JOYSTICK::IButtonMap::AddThrottle	(	const FeatureName &	feature,
		THROTTLE_DIRECTION	direction,
		const CDriverPrimitive &	primitive )

pure virtual

Add or update a throttle direction.

Parameters

feature	Must be a throttle or this will return false
direction	The direction being mapped
primitive	The driver primitive for the specified analog stick and direction

Returns: True if the analog stick was updated, false otherwise

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ AddWheel()

virtual void KODI::JOYSTICK::IButtonMap::AddWheel	(	const FeatureName &	feature,
		WHEEL_DIRECTION	direction,
		const CDriverPrimitive &	primitive )

pure virtual

Add or update a wheel direction.

Parameters

feature	Must be a wheel or this will return false
direction	The direction being mapped
primitive	The driver primitive for the specified analog stick and direction

Returns: True if the analog stick was updated, false otherwise

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ ControllerID()

virtual std::string KODI::JOYSTICK::IButtonMap::ControllerID ( void ) const

pure virtual

The add-on ID of the game controller associated with this button map.

The controller ID provided by the implementation serves as the context for the feature names below.

Returns: The ID of this button map's game controller add-on

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetAccelerometer()

virtual bool KODI::JOYSTICK::IButtonMap::GetAccelerometer	(	const FeatureName &	feature,
		CDriverPrimitive &	positiveX,
		CDriverPrimitive &	positiveY,
		CDriverPrimitive &	positiveZ )

pure virtual

Get an accelerometer from the button map.

Parameters

feature	Must be an accelerometer or this will return false
positiveX	The semiaxis mapped to the positive X direction (possibly unknown)
positiveY	The semiaxis mapped to the positive Y direction (possibly unknown)
positiveZ	The semiaxis mapped to the positive Z direction (possibly unknown)

Returns: True if the feature resolved to an accelerometer with at least 1 known axis

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetAnalogStick()

virtual bool KODI::JOYSTICK::IButtonMap::GetAnalogStick	(	const FeatureName &	feature,
		ANALOG_STICK_DIRECTION	direction,
		CDriverPrimitive &	primitive )

pure virtual

Get an analog stick direction from the button map.

Parameters

	feature	Must be an analog stick or this will return false
	direction	The direction whose primitive is to be retrieved
[out]	primitive	The primitive mapped to the specified direction

Returns: True if the feature and direction resolved to a driver primitive

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetAppearance()

virtual std::string KODI::JOYSTICK::IButtonMap::GetAppearance ( ) const

pure virtual

Get the ID of the controller profile that best represents the appearance of the peripheral.

Returns: The controller ID, or empty if the appearance is unknown

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetAxisProperties()

virtual bool KODI::JOYSTICK::IButtonMap::GetAxisProperties	(	unsigned int	axisIndex,
		int &	center,
		unsigned int &	range )

pure virtual

Get the properties of an axis.

Parameters

axisIndex	The index of the axis to check
center[out]	The center, if known
range[out]	The range, if known

Returns: True if the properties are known, false otherwise

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetFeature()

virtual bool KODI::JOYSTICK::IButtonMap::GetFeature	(	const CDriverPrimitive &	primitive,
		FeatureName &	feature )

pure virtual

Get the feature associated with a driver primitive.

Multiple primitives can be mapped to the same feature. For example, analog sticks use one primitive for each direction.

Parameters

primitive	The driver primitive
feature	The name of the resolved joystick feature, or invalid if false is returned

Returns: True if the driver primitive is associated with a feature, false otherwise

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetFeatureType()

virtual FEATURE_TYPE KODI::JOYSTICK::IButtonMap::GetFeatureType ( const FeatureName & feature )

pure virtual

Get the type of the feature for the given name.

Parameters

feature The feature to look up

Returns: The feature's type

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetKey()

virtual bool KODI::JOYSTICK::IButtonMap::GetKey	(	const FeatureName &	feature,
		CDriverPrimitive &	primitive )

pure virtual

Get the driver primitive for a keyboard key.

Parameters

feature	Must be a key
primitive	The resolved driver primitive

Returns: True if the feature resolved to a driver primitive, false if the feature didn't resolve or isn't a scalar feature

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetRelativePointer()

virtual bool KODI::JOYSTICK::IButtonMap::GetRelativePointer	(	const FeatureName &	feature,
		RELATIVE_POINTER_DIRECTION	direction,
		CDriverPrimitive &	primitive )

pure virtual

Get a relative pointer direction from the button map.

Parameters

	feature	Must be a relative pointer stick or this will return false
	direction	The direction whose primitive is to be retrieved
[out]	primitive	The primitive mapped to the specified direction

Returns: True if the feature and direction resolved to a driver primitive

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetScalar()

virtual bool KODI::JOYSTICK::IButtonMap::GetScalar	(	const FeatureName &	feature,
		CDriverPrimitive &	primitive )

pure virtual

Get the driver primitive for a scalar feature.

When a feature can be represented by a single driver primitive, it is called a scalar feature.

This includes buttons and triggers, because they can be mapped to a single button/hat/semiaxis
This does not include analog sticks, because they require two axes and four driver primitives (one for each semiaxis)

Parameters

feature	Must be a scalar feature (a feature that only requires a single driver primitive)
primitive	The resolved driver primitive

Returns: True if the feature resolved to a driver primitive, false if the feature didn't resolve or isn't a scalar feature

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetThrottle()

virtual bool KODI::JOYSTICK::IButtonMap::GetThrottle	(	const FeatureName &	feature,
		THROTTLE_DIRECTION	direction,
		CDriverPrimitive &	primitive )

pure virtual

Get a throttle direction from the button map.

Parameters

	feature	Must be a throttle or this will return false
	direction	The direction whose primitive is to be retrieved
[out]	primitive	The primitive mapped to the specified direction

Returns: True if the feature and direction resolved to a driver primitive

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ GetWheel()

virtual bool KODI::JOYSTICK::IButtonMap::GetWheel	(	const FeatureName &	feature,
		WHEEL_DIRECTION	direction,
		CDriverPrimitive &	primitive )

pure virtual

Get a wheel direction from the button map.

Parameters

	feature	Must be a wheel or this will return false
	direction	The direction whose primitive is to be retrieved
[out]	primitive	The primitive mapped to the specified direction

Returns: True if the feature and direction resolved to a driver primitive

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ IsEmpty()

virtual bool KODI::JOYSTICK::IButtonMap::IsEmpty ( void ) const

pure virtual

Check if the button map is empty.

Returns: True if the button map is empty, false if it has features

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ IsIgnored()

virtual bool KODI::JOYSTICK::IButtonMap::IsIgnored ( const CDriverPrimitive & primitive )

pure virtual

Check if a primitive is in the list of primitives to be ignored.

Parameters

primitive The primitive to check

Returns: True if the primitive should be ignored in the mapping process

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ Load()

virtual bool KODI::JOYSTICK::IButtonMap::Load ( void )

pure virtual

Load the button map into memory.

Returns: True if button map is ready to start translating buttons, false otherwise

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ Location()

virtual std::string KODI::JOYSTICK::IButtonMap::Location ( void ) const

pure virtual

The Location of the peripheral associated with this button map.

Returns: The peripheral's location

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ Reset()

virtual void KODI::JOYSTICK::IButtonMap::Reset ( void )

pure virtual

Reset the button map to its defaults, or clear button map if no defaults.

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ RevertButtonMap()

virtual void KODI::JOYSTICK::IButtonMap::RevertButtonMap ( )

pure virtual

Revert changes to the button map since the last time it was loaded or committed to disk.

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ SaveButtonMap()

virtual void KODI::JOYSTICK::IButtonMap::SaveButtonMap ( )

pure virtual

Save the button map.

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ SetAppearance()

virtual bool KODI::JOYSTICK::IButtonMap::SetAppearance ( const std::string & controllerId ) const

pure virtual

Set the ID of the controller that best represents the appearance of the peripheral.

Parameters

controllerId The controller ID, or empty to unset the appearance

Returns: True if the appearance was set, false on error

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

◆ SetIgnoredPrimitives()

virtual void KODI::JOYSTICK::IButtonMap::SetIgnoredPrimitives ( const std::vector< CDriverPrimitive > & primitives )

pure virtual

Set a list of driver primitives to be ignored.

This is necessary to prevent features from interfering with the button mapping process. This includes accelerometers, as well as PS4 triggers which send both a button press and an analog value.

Parameters

primitives The driver primitives to be ignored

Implemented in KODI::GAME::CDefaultButtonMap, and PERIPHERALS::CAddonButtonMap.

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

IButtonMap.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IButtonMap()

Member Function Documentation

◆ AddAccelerometer()

◆ AddAnalogStick()

◆ AddKey()

◆ AddRelativePointer()

◆ AddScalar()

◆ AddThrottle()

◆ AddWheel()

◆ ControllerID()

◆ GetAccelerometer()

◆ GetAnalogStick()

◆ GetAppearance()

◆ GetAxisProperties()

◆ GetFeature()

◆ GetFeatureType()

◆ GetKey()

◆ GetRelativePointer()

◆ GetScalar()

◆ GetThrottle()

◆ GetWheel()

◆ IsEmpty()

◆ IsIgnored()

◆ Load()

◆ Location()

◆ Reset()

◆ RevertButtonMap()

◆ SaveButtonMap()

◆ SetAppearance()

◆ SetIgnoredPrimitives()