The TouchState class represent the internal states during touch interaction. More...

#include <TouchState.hh>

Collaboration diagram for gramods::gmTouch::TouchState:

[legend]

Classes
struct	CameraAdaptor
	Base type for camera adaptors providing means to input camera data from different scenegraph or graphics platforms. More...

struct	EventAdaptor
	Base type for event adaptors providing means to input events from different platforms and window libraries. More...

struct	State
	Touch states that can be bitwise combined (except NONE). More...

struct	TouchLine
	A 3D line representation of a touch point. More...

struct	TouchPoint
	A single (potentially smoothed) touch point. More...

Public Types
typedef std::chrono::steady_clock	clock
	The clock used in this class.

typedef int64_t	TouchPointId
	The internal type of a touch point id.

typedef std::vector< TouchPoint >	TouchPoints
	List of touch points.

typedef std::vector< TouchLine >	TouchLines
	List of touch lines.

Public Member Functions
	TouchState ()
	Creates an empty TouchState instance.

	~TouchState ()
	Destroys the TouchState instance.

Get touch points
Methods used to extract current touch points and the their states.
bool	empty () const
	Checks whether the TouchState is empty of touch points.

int	getTouchPoints (TouchPoints &current) const
	Gets the current touch points, and returns the point count.

int	getTouchPoints (TouchPoints &current, TouchPoints &previous) const
	Gets the current touch points and their corresponding previous positions, and returns the point count.

int	getTouchPoints (void *ass, TouchPoints &current) const
	Gets the current touch points associated to the specified pointer, and returns the point count.

int	getTouchPoints (void *ass, TouchPoints &current, TouchPoints &previous) const
	Gets the current touch points associated to the specified pointer, and their corresponding previous positions, and returns the point count.

int	getTouchPoints (std::map< void *, TouchPoints > &current) const
	Gets the current touch points as an association map.

int	getTouchPoints (std::map< void , TouchPoints > &current, std::map< void , TouchPoints > &previous) const
	Gets the current touch points as an association map.

bool	setAssociation (TouchPointId id, void *pt)
	Associates an unassociated touch point id with an object.

bool	unsetAssociation (TouchPointId id, void *pt)
	Removes the association of the specified touch point id with the specified object.

bool	getAssociation (TouchPointId id, void **pt) const
	Gets the touch point id associated with a specified object.

Mouse simulation methods
Methods used to allow interaction with mouse, when touch is not available.
float	getMouseWheel () const
	Returns the mouse wheel value, positive up and negative down.

bool	getMouseDown () const
	Returns true if the mouse button is down, false otherwise.

void	getMousePoint (int &x, int &y) const
	Get the point point.

bool	getMouseLine (Eigen::Vector3f &x, Eigen::Vector3f &v) const
	Get the point point as a touch line.

Parameters
Methods used to adjust the general behaviour of the class.
void	setSmoothing (float r)
	Sets the level of smoothing to use, to reduce jerky actions caused by noisy and jittery input devices.

float	getSmoothing ()
	Gets the level of smoothing currently in use.

void	setRemoveMouseUponTouch (bool on)
	Incoming mouse events are used to simulate touch, but if this is set to true (default) this behaviour is deactivated upon incoming touch events.

bool	getRemoveMouseUponTouch ()
	Gets the mouse filtering state.

void	setMoveMagnitude (float dist)
	Sets the magnitude of movement (Euclidean distance in pixels, default 10) that is allowed before the touch point is considered to be moved.

float	getMoveMagnitude ()
	Gets the movement magnitude that is considered a touch movement.

void	setHoldTime (clock::duration time)
	Sets the time that a touch point must be held without being dragged before its state get the HOLD flag, default 2 seconds.

clock::duration	getHoldTime ()
	Gets the hold time.

void	setClickTime (clock::duration time)
	Sets the time that a touch point can be held before release to get a CLICK flag, default 500 ms.

clock::duration	getClickTime ()
	Gets the click time.

void	setMultiClickTime (clock::duration time)
	Sets the maximum amount of time (default 500 ms) between two touches at the same point that is considered a multi click of the same touch point.

clock::duration	getMultiClickTime ()
	Gets the multi click time.

Static Public Attributes
static const TouchPointId	MOUSE_STATE_ID = std::numeric_limits<TouchPointId>::max()
	The touch point id used for mouse pointer simulating touch.

3D projection methods
Methods used handle touch states' 3D behaviour.
friend	CameraAdaptor

void	setCurrentProjection (Eigen::Matrix4f WPV_inv)
	Sets the current (inverted) projection matrix to use when back-projecting the 2D touch points into 3D.

template<class T >
T &	getCameraAdaptor ()
	Returns a reference to the internal camera adaptor for the specified type.

bool	getTouchLines (TouchLines &current) const
	Gets the current touch lines and returns true, if lines can be extracted from the current touch points.

bool	getTouchLines (TouchLines &current, TouchLines &previous) const
	Gets the current and previous touch lines and returns true, if lines can be extracted from the current and previous touch points.

bool	getTouchLines (void *ass, TouchLines &current) const
	Gets the current touch lines and returns true, if lines can be extracted from the current touch points.

bool	getTouchLines (void *ass, TouchLines &current, TouchLines &previous) const
	Gets the current and previous touch lines and returns true, if lines can be extracted from the current and previous touch points.

bool	getTouchLines (std::map< void *, TouchLines > &current) const
	Gets the current touch lines as an association map.

bool	getTouchLines (std::map< void , TouchLines > &current, std::map< void , TouchLines > &previous) const
	Gets the current touch lines as an association map.

Updating internal states
Methods used to fill and update the set of states.
friend	EventAdaptor

template<class T >
T &	getEventAdaptor ()
	Returns a reference to the internal event adaptor for the specified type.

void	eventsInit (int width, int height)
	Initializes the event handling.

void	eventsDone ()
	Flags the internal touch states as complete.

Detailed Description

The TouchState class represent the internal states during touch interaction.

It supports association of touch points with objects, "multi click" (double click and more), and provides states to differentiate between dragging and held touch points. For example, a user may tripple click, hold and then drag, which is then reflected by the internal states of the touch point. For example, an object may choose to associate a touch point to itself only if it represents a tripple click-and-hold-then-drag.

Typical usage:

// Copy event data into TouchState object (in SDL window handler) ---
touchState.eventsInit(width, height);
touchState.setCurrentProjection(camera);
 
SDL_Event event;
while(SDL_PollEvent(&event)) {
  touchState.getEventAdaptor<gmTouch::SDLEventAdaptor>().handleEvent(event);
}
touchState.eventsDone();
 
...
 
// Associate touch points with this object (in interaction object class) ---
TouchPoints touchPoints;
if (touchState.getTouchPoints(this, touchPoints) < REQUIRED_POINTS) {
  TouchPoints candidates;
  touchState.getTouchPoints(nullptr, candidates);
  for (auto& pt : candidates)
    if (isInside(pt.x, pt.y)) // Checks if the point hits this object
      touchState.setAssociation(pt.id, this);
}
 
TouchPoints currentTouchPoints, previousTouchPoints;
if (touchState.getTouchPoints(this, currentTouchPoints, previousTouchPoints) < REQUIRED_POINTS)
  return;
 
// Use touch points here

Member Typedef Documentation

◆ clock

typedef std::chrono::steady_clock gramods::gmTouch::TouchState::clock

The clock used in this class.

◆ TouchLines

typedef std::vector<TouchLine> gramods::gmTouch::TouchState::TouchLines

List of touch lines.

◆ TouchPointId

typedef int64_t gramods::gmTouch::TouchState::TouchPointId

The internal type of a touch point id.

Observe that the underlying event system may use a different type and wrap around at any value.

◆ TouchPoints

typedef std::vector<TouchPoint> gramods::gmTouch::TouchState::TouchPoints

List of touch points.

Constructor & Destructor Documentation

◆ TouchState()

gramods::gmTouch::TouchState::TouchState ( )

Creates an empty TouchState instance.

◆ ~TouchState()

gramods::gmTouch::TouchState::~TouchState ( )

Destroys the TouchState instance.

Member Function Documentation

◆ empty()

bool gramods::gmTouch::TouchState::empty ( ) const

inline

Checks whether the TouchState is empty of touch points.

◆ eventsDone()

void gramods::gmTouch::TouchState::eventsDone ( )

Flags the internal touch states as complete.

Call this after calling handleEvent with all currently available events.

◆ eventsInit()

void gramods::gmTouch::TouchState::eventsInit	(	int	width,
		int	height
	)

Initializes the event handling.

Call this before calling handleEvents.

Parameters

[in]	width	The current view width in pixels
[in]	height	The current view height in pixels

◆ getAssociation()

bool gramods::gmTouch::TouchState::getAssociation	(	TouchPointId	id,
		void **	pt
	)		const

Gets the touch point id associated with a specified object.

Parameters

[in]	id	The id of the touch point that is associated.
[out]	pt	A pointer to a void pointer, set to the pointer that is associated with the provided id, or nullptr if only found/not found is of interest.

Returns: True iff an association was found.

◆ getCameraAdaptor()

template<class T >

T & gramods::gmTouch::TouchState::getCameraAdaptor ( )

Returns a reference to the internal camera adaptor for the specified type.

The adaptor is instantiated upon the first call to this method and deleted when the TouchState is destroyed.

◆ getClickTime()

TouchState::clock::duration gramods::gmTouch::TouchState::getClickTime ( )

Gets the click time.

See also: setClickTime

◆ getEventAdaptor()

template<class T >

T & gramods::gmTouch::TouchState::getEventAdaptor ( )

Returns a reference to the internal event adaptor for the specified type.

The adaptor is instantiated upon the first call to this method and deleted when the TouchState is destroyed.

◆ getHoldTime()

TouchState::clock::duration gramods::gmTouch::TouchState::getHoldTime ( )

Gets the hold time.

See also: setHoldTime

◆ getMouseDown()

bool gramods::gmTouch::TouchState::getMouseDown ( ) const

Returns true if the mouse button is down, false otherwise.

◆ getMouseLine()

bool gramods::gmTouch::TouchState::getMouseLine	(	Eigen::Vector3f &	x,
		Eigen::Vector3f &	v
	)		const

Get the point point as a touch line.

Returns true if the line could be calculated.

◆ getMousePoint()

void gramods::gmTouch::TouchState::getMousePoint	(	int &	x,
		int &	y
	)		const

Get the point point.

◆ getMouseWheel()

float gramods::gmTouch::TouchState::getMouseWheel ( ) const

Returns the mouse wheel value, positive up and negative down.

◆ getMoveMagnitude()

float gramods::gmTouch::TouchState::getMoveMagnitude ( )

Gets the movement magnitude that is considered a touch movement.

See also: setMoveMagnitude

◆ getMultiClickTime()

TouchState::clock::duration gramods::gmTouch::TouchState::getMultiClickTime ( )

Gets the multi click time.

See also: setMultiClickTime

◆ getRemoveMouseUponTouch()

bool gramods::gmTouch::TouchState::getRemoveMouseUponTouch ( )

Gets the mouse filtering state.

See also: setRemoveMouseUponTouch

◆ getSmoothing()

float gramods::gmTouch::TouchState::getSmoothing ( )

Gets the level of smoothing currently in use.

See also: setSmoothing

◆ getTouchLines() [1/6]

bool gramods::gmTouch::TouchState::getTouchLines ( std::map< void *, TouchLines > & current ) const

Gets the current touch lines as an association map.

Unassociated touch lines will be associated with nullptr.

Parameters

[out] current The association map between objects (or nullptr) and their associated touch lines.

Returns: True if both current lines could be extracted.

◆ getTouchLines() [2/6]

bool gramods::gmTouch::TouchState::getTouchLines	(	std::map< void *, TouchLines > &	current,
		std::map< void *, TouchLines > &	previous
	)		const

Gets the current touch lines as an association map.

Unassociated touch lines will be associated with nullptr.

Parameters

[out]	current	The association map between objects (or nullptr) and their associated touch lines.
[out]	previous	The association map between objects (or nullptr) and their associated previous touch lines.

Returns: True if both current and previous lines could be extracted.

◆ getTouchLines() [3/6]

bool gramods::gmTouch::TouchState::getTouchLines ( TouchLines & current ) const

Gets the current touch lines and returns true, if lines can be extracted from the current touch points.

False is returned otherwise.

Parameters

[out] current The resulting 3D lines, originating at the near plane.

Returns: True if current lines could be extracted.

◆ getTouchLines() [4/6]

bool gramods::gmTouch::TouchState::getTouchLines	(	TouchLines &	current,
		TouchLines &	previous
	)		const

Gets the current and previous touch lines and returns true, if lines can be extracted from the current and previous touch points.

False is returned otherwise.

Parameters

[out]	current	The current 3D lines, originating at the near plane.
[out]	previous	The previous 3D lines, originating at the near plane.

Returns: True if both current and previous lines could be extracted.

◆ getTouchLines() [5/6]

bool gramods::gmTouch::TouchState::getTouchLines	(	void *	ass,
		TouchLines &	current
	)		const

Gets the current touch lines and returns true, if lines can be extracted from the current touch points.

False is returned otherwise.

Parameters

[in]	ass
[out]	current	The resulting 3D lines, originating at the near plane.

Returns: True if current lines could be extracted.

◆ getTouchLines() [6/6]

bool gramods::gmTouch::TouchState::getTouchLines	(	void *	ass,
		TouchLines &	current,
		TouchLines &	previous
	)		const

Gets the current and previous touch lines and returns true, if lines can be extracted from the current and previous touch points.

False is returned otherwise.

Parameters

[in]	ass
[out]	current	The current 3D lines, originating at the near plane.
[out]	previous	The previous 3D lines, originating at the near plane.

Returns: True if both current and previous lines could be extracted.

◆ getTouchPoints() [1/6]

int gramods::gmTouch::TouchState::getTouchPoints ( std::map< void *, TouchPoints > & current ) const

Gets the current touch points as an association map.

Unassociated touch points will be associated with nullptr.

Parameters

[out] current The association map between objects (or nullptr) and their associated touch points.

◆ getTouchPoints() [2/6]

int gramods::gmTouch::TouchState::getTouchPoints	(	std::map< void *, TouchPoints > &	current,
		std::map< void *, TouchPoints > &	previous
	)		const

Gets the current touch points as an association map.

Unassociated touch points will be associated with nullptr.

Parameters

[out]	current	The association map between objects (or nullptr) and their associated touch points.
[out]	previous	The association map between objects (or nullptr) and their associated previous touch points.

◆ getTouchPoints() [3/6]

int gramods::gmTouch::TouchState::getTouchPoints ( TouchPoints & current ) const

Gets the current touch points, and returns the point count.

Parameters

[out] current The resulting touch points.

Returns: The number of touch points extracted.

◆ getTouchPoints() [4/6]

int gramods::gmTouch::TouchState::getTouchPoints	(	TouchPoints &	current,
		TouchPoints &	previous
	)		const

Gets the current touch points and their corresponding previous positions, and returns the point count.

This will only provide touch points with both current and previous states available.

Parameters

[out]	current	The most current touch points.
[out]	previous	The touch points from the previous time frame.

Returns: The number of touch points extracted.

◆ getTouchPoints() [5/6]

int gramods::gmTouch::TouchState::getTouchPoints	(	void *	ass,
		TouchPoints &	current
	)		const

Gets the current touch points associated to the specified pointer, and returns the point count.

Unassociated touch points can be extraced with nullptr as first argument.

Parameters

[in]	ass	The association to extract touch points for, or nullptr for unassociated points.
[out]	current	The resulting touch points.

Returns: The number of touch points extracted.

◆ getTouchPoints() [6/6]

int gramods::gmTouch::TouchState::getTouchPoints	(	void *	ass,
		TouchPoints &	current,
		TouchPoints &	previous
	)		const

Gets the current touch points associated to the specified pointer, and their corresponding previous positions, and returns the point count.

This will only provide touch points with both current and previous states available. Unassociated touch points can be extraced with nullptr as first argument.

Parameters

[in]	ass	The association to extract touch points for, or nullptr for unassociated points.
[out]	current	The resulting touch points.
[out]	previous	The touch points from the previous time frame.

Returns: The number of touch points extracted.

◆ setAssociation()

bool gramods::gmTouch::TouchState::setAssociation	(	TouchPointId	id,
		void *	pt
	)

Associates an unassociated touch point id with an object.

Parameters

[in]	id	The touch point id that should be associated.
[in]	pt	A void pointer to the object to associate with.

Returns: True iff an association was successfully created.

◆ setClickTime()

void gramods::gmTouch::TouchState::setClickTime ( clock::duration time )

Sets the time that a touch point can be held before release to get a CLICK flag, default 500 ms.

◆ setCurrentProjection()

void gramods::gmTouch::TouchState::setCurrentProjection ( Eigen::Matrix4f WPV_inv )

Sets the current (inverted) projection matrix to use when back-projecting the 2D touch points into 3D.

This can be calculated by inverting the matrix product of 1) viewport window matrix, 2) projection matrix and 3) view matrix (W*P*V)^-1, when using column vector matrices.

It is more convenient to use a TouchState::CameraAdaptor.

If the view changes changing over time, one of these methods needs to be called every frame, between calling eventsInit and eventsDone and before extrating 3D lines. If the view is static, the method needs to be called at least twice, to make the current matrix be copied to previous state.

See also: TouchState::getTouchLines

◆ setHoldTime()

void gramods::gmTouch::TouchState::setHoldTime ( clock::duration time )

Sets the time that a touch point must be held without being dragged before its state get the HOLD flag, default 2 seconds.

◆ setMoveMagnitude()

void gramods::gmTouch::TouchState::setMoveMagnitude ( float dist )

Sets the magnitude of movement (Euclidean distance in pixels, default 10) that is allowed before the touch point is considered to be moved.

This affects when the states State::DRAG and State::MULTI are applied. Also, velocity estimation uses this value as a measure of touch noise.

Parameters

[in] dist Euclidean distance in pixels

◆ setMultiClickTime()

void gramods::gmTouch::TouchState::setMultiClickTime ( clock::duration time )

Sets the maximum amount of time (default 500 ms) between two touches at the same point that is considered a multi click of the same touch point.

◆ setRemoveMouseUponTouch()

void gramods::gmTouch::TouchState::setRemoveMouseUponTouch ( bool on )

Incoming mouse events are used to simulate touch, but if this is set to true (default) this behaviour is deactivated upon incoming touch events.

◆ setSmoothing()

void gramods::gmTouch::TouchState::setSmoothing ( float r )

Sets the level of smoothing to use, to reduce jerky actions caused by noisy and jittery input devices.

The value must be between zero (inclusive, representing no smoothing, which is the default) and one (exclusive, representing no motion).

◆ unsetAssociation()

bool gramods::gmTouch::TouchState::unsetAssociation	(	TouchPointId	id,
		void *	pt
	)

Removes the association of the specified touch point id with the specified object.

Parameters

[in]	id	The touch point id that should be unassociated.
[in]	pt	A void pointer to the currently associated object.

Returns: True iff an association was successfully removed.

Member Data Documentation

◆ MOUSE_STATE_ID

const TouchState::TouchPointId gramods::gmTouch::TouchState::MOUSE_STATE_ID = std::numeric_limits<TouchPointId>::max()

static

The touch point id used for mouse pointer simulating touch.

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

/home/karlu/private/program/gramods/modules/gmTouch/include/gmTouch/TouchState.hh
/home/karlu/private/program/gramods/modules/gmTouch/src/TouchState.cpp

Classes

Public Types

Public Member Functions

Static Public Attributes

3D projection methods

Updating internal states

Detailed Description

Member Typedef Documentation

◆ clock

◆ TouchLines

◆ TouchPointId

◆ TouchPoints

Constructor & Destructor Documentation

◆ TouchState()

◆ ~TouchState()

Member Function Documentation

◆ empty()

◆ eventsDone()

◆ eventsInit()

◆ getAssociation()

◆ getCameraAdaptor()

◆ getClickTime()

◆ getEventAdaptor()

◆ getHoldTime()

◆ getMouseDown()

◆ getMouseLine()

◆ getMousePoint()

◆ getMouseWheel()

◆ getMoveMagnitude()

◆ getMultiClickTime()

◆ getRemoveMouseUponTouch()

◆ getSmoothing()

◆ getTouchLines() [1/6]

◆ getTouchLines() [2/6]

◆ getTouchLines() [3/6]

◆ getTouchLines() [4/6]

◆ getTouchLines() [5/6]

◆ getTouchLines() [6/6]

◆ getTouchPoints() [1/6]

◆ getTouchPoints() [2/6]

◆ getTouchPoints() [3/6]

◆ getTouchPoints() [4/6]

◆ getTouchPoints() [5/6]

◆ getTouchPoints() [6/6]

◆ setAssociation()

◆ setClickTime()

◆ setCurrentProjection()

◆ setHoldTime()

◆ setMoveMagnitude()

◆ setMultiClickTime()

◆ setRemoveMouseUponTouch()

◆ setSmoothing()

◆ unsetAssociation()

Member Data Documentation

◆ MOUSE_STATE_ID