SoPointingAction is the base class for any mouse based interaction. More...

#include <SoPointingAction.h>

Inheritance diagram for SoPointingAction:

Public Types
enum	StopMode { AbortAction , FinishAction }
	Argument type for releaseGrab() More...

enum	{ Button1Mask = ManagedMouseButtonTrigger::Button1Mask , Button2Mask = ManagedMouseButtonTrigger::Button2Mask , Button3Mask = ManagedMouseButtonTrigger::Button3Mask , AllButtonsMask = ManagedMouseButtonTrigger::AllButtonsMask }
	Configuration values for the Trigger type. More...

enum	{ TypeId = TypePointingAction }

typedef ManagedMouseButtonTrigger	Trigger
	Class Trigger encapsulates the combination of required and ignored button and modifier keys that activate a pointing action.

typedef std::list< Trigger >	TriggerList
	List of triggers.

Public Types inherited from SoInteraction
enum	{ NoModifier = ManagedActionTrigger::NoModifier , ShiftModifier = ManagedActionTrigger::ShiftModifier , ControlModifier = ManagedActionTrigger::ControlModifier , AltModifier = ManagedActionTrigger::AltModifier , AllModifiersMask = ManagedActionTrigger::AllModifiersMask , ShiftMask = ShiftModifier , CtrlMask = ControlModifier , AltMask = AltModifier }
	Constants to use where keyboard modifiers must be specified. More...

enum	InteractionType { TypePointingAction , TypeCommandAction , TypeOffsetAction }
	Enum identifying sub-types of this class. More...

Public Member Functions
	SoPointingAction (SoInteractionOwner *owner, std::string id, bool positionSensitive=true)
	Standard constructor.

virtual bool	isPositionSensitive () const
	Position sensitive actions can only start at positions where isSensitiveAt() return true.

void	clearTriggers ()
	remove all triggers

void	setTrigger (int triggerMask, int ignoreMask=0)
	Sets the (only) default modifier/button mask for triggering this action.

void	setTrigger (const Trigger &trigger)
	Same with Trigger object.

void	addTrigger (const Trigger &trigger)
	Adds another default modifier/button mask as trigger.

TriggerList	getTriggers () const
	Returns the list of default modifier/button mask combinations set for this action.

virtual bool	triggersAction (int mask)
	Returns whether the given modifier/button combination activates this action according to the default bindings.

virtual int	getNumModes () const
	Returns the number of different modes this action has - modes can be changed during drag and handle drag restrictions or drag result.

virtual int	getCurrentCursor (SoViewerProxy *) const
	Returns the cursor ID to display for this action, as defined in SoViewerProxy.h - this gets (at least) called after setMode(), isSensitiveAt(), startPressAt(), dragMoveTo(), and endPress().

virtual std::string	getCurrentStatusMessage () const
	Returns a status message for display in status bar (make it short!), this will get called at same time as getCurrentCursor.

virtual void	setMode (int)
	This gets called if the mode was changed and before startPressAt is called.

virtual bool	isSensitiveAt (const SoPointerPosition &pos)=0
	Returns true if the gesture is startable at the given device position.

virtual void	setHighlightAt (const SoPointerPosition &)
	This method is called so that highlighting of objects under the mouse cursor can occur.

virtual void	unsetHighlight ()
	Remove any highlighting if this method is called.

virtual void	startPressAt (const SoPointerPosition &pos)=0
	Starts a drag at given device position.

virtual void	dragMoveTo (const SoPointerPosition &pos)=0
	Continues the drag to given device position.

virtual SoPointingAction *	endPress (int clickCount)=0
	Ends the drag at last device position.

virtual void	dragCancelled ()
	This is called if the current drag operation is cancelled, e.g.

virtual bool	wantsMouseOverUpdates ()
	Override this to return true if this action should get location updates directly before rendering, so it can update its status.

void	grabReleased ()
	Call this to release an interaction grab that has been established by the return value of endPress(), e.g., because it was aborted through a SoCommandAction.

virtual void	releaseGrab (StopMode)
	This will be called by the controller if you should release the grab established by endPress.

virtual bool	wantsImmediateDragUpdates ()
	Let this method return false if you don't want dragMoveTo to be called until it is clear that the interaction will not be handled as a click (endPress will be called with a clickCount greater zero).

Public Member Functions inherited from SoInteraction
	SoInteraction (InteractionType type, SoInteractionOwner *owner, const std::string &id, bool registerWithOwner=true)
	Standard constructor.

virtual	~SoInteraction ()
	Virtual destructor.

SoInteractionOwner *	getOwner () const

virtual bool	isEnabled () const

virtual void	setEnabled (bool enabled)
	Sets the enabled status of this interaction.

std::string	getID () const

void	setID (const std::string &id)
	Sets the id of this interaction.

std::string	getFullID () const
	Returns the ID string consisting of the id of the provider and this action's id, separated by '.

InteractionType	getInteractionType () const
	Get type of interaction object.

template<class T >
bool	isOfType () const
	Convenience method for checking type.

int	getMenuPriority () const

void	setMenuPriority (int priority)
	Sets the priority value for ordered display in menus/tool boxes.

virtual std::string	getUserName () const

virtual void	setUserName (const std::string &name)
	Sets the user name of this interaction entry.

virtual std::string	getIconFile () const

virtual void	setIconFile (const std::string &file)
	Sets the filename of an icon used for this interaction entry.

virtual std::string	getDescription () const

virtual void	setDescription (const std::string &descr)
	Sets the description for user help.

virtual void	ref ()

virtual void	unref ()

int	getStateVersion () const

void	touch ()
	Increments the version number of attribute state to mark attribute changes.

Protected Member Functions
virtual SoOffsetAction *	proxiedOffsetAction () const

Friends
class	SoInteractionCoordinator

class	SoOffsetPointingAction

Detailed Description

SoPointingAction is the base class for any mouse based interaction.

Several SoPointingActions may be available for a given scene; the interaction controller will select one PointingAction based on pressed mouse buttons and key modifiers and whether the isSensitiveAt() method returns true for the current position or if the isPositionSensitive() flag returns false altogether.

While no button is pressed the interaction controller still will keep track of the SoPointingAction that would get activated if the left mouse button was pressed with the current key modifiers. For this action the cursor shape returned from getCurrentCursor() will be shown. Additionally the method setHighlightAt() will be called with the current position. This is done continuously. If another action gets candidate for activation, e.g., because isSensitiveAt() returns false or because the key modifiers change, unsetHighlight() will be called for the old action. This can be used to highlight objects under the mouse cursor.

If the correct mouse button/key modifier combination is pressed, startPressAt() will be called at the current position. Mouse moves while dragging will result in dragMoveTo() calls. If the last mouse button is released, endPress() is called. It is guaranteed that the selected SoPointingAction will get the endPress() call after the startPressAt(), with intervening dragMoveTo() calls.

SoPointingActions that do not have the isPositionSensitive() flag set behave slightly different. This flag, that can be set from the constructor, is meant to mark position specific actions. If this flag is not set, this marks mouse interactions that really are general gestures. isSensitiveAt() is not called for these actions, and there is no requirement that all buttons must be released to get the endPress() call. Rather it is possible to switch directly to another position-insensitive action by changing the pressed mouse button/key modifier combination.

A SoPointingAction might have several modes to influence dragging behavior. The number of possible modes can be set through getNumModes(), and the controller will call setMode() depending on the current key modifiers (which these are is currently up to the controller implementation). Note that this only influences the behavior while dragging. If you need to implement different behavior from the start of the dragging you should provide different SoPointingAction objects.

Summary:

Methods you want to override in any case:

isSensitiveAt()
getCurrentCursor()
startPressAt()
dragMoveTo()
endPress()

Methods you want to override if you do highlighting of objects:

setHighlightAt()
unsetHighlight()

Methods you need to override if you have different dragging modes:

getNumModes()
setMode()

Definition at line 88 of file SoPointingAction.h.

Member Typedef Documentation

◆ Trigger

typedef ManagedMouseButtonTrigger SoPointingAction::Trigger

Class Trigger encapsulates the combination of required and ignored button and modifier keys that activate a pointing action.

Definition at line 113 of file SoPointingAction.h.

◆ TriggerList

typedef std::list<Trigger> SoPointingAction::TriggerList

List of triggers.

Definition at line 116 of file SoPointingAction.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Configuration values for the Trigger type.

You can combine these with the key modifier values from SoInteraction

Enumerator
Button1Mask	Left button.
Button2Mask	Middle button.
Button3Mask	Right button.
AllButtonsMask	All buttons.

Definition at line 102 of file SoPointingAction.h.

◆ anonymous enum

anonymous enum

Enumerator
TypeId

Definition at line 109 of file SoPointingAction.h.

◆ StopMode

enum SoPointingAction::StopMode

Argument type for releaseGrab()

Enumerator
AbortAction	Current action should be aborted.
FinishAction	Current action should be finished.

Definition at line 95 of file SoPointingAction.h.

Constructor & Destructor Documentation

◆ SoPointingAction()

SoPointingAction::SoPointingAction	(	SoInteractionOwner *	owner,
		std::string	id,
		bool	positionSensitive = true )

Standard constructor.

Parameters

owner	is the SoInteractionOwner to which the action is added. Ownership is automatically transferred, you don't need to free this object.
id	is the name of this interaction, it should hint at its purpose
positionSensitive	sets the return value of isPositionSensitive()

Member Function Documentation

◆ addTrigger()

void SoPointingAction::addTrigger ( const Trigger & trigger )

Adds another default modifier/button mask as trigger.

◆ clearTriggers()

void SoPointingAction::clearTriggers ( )

inline

remove all triggers

Definition at line 134 of file SoPointingAction.h.

◆ dragCancelled()

virtual void SoPointingAction::dragCancelled ( )

inlinevirtual

This is called if the current drag operation is cancelled, e.g.

through a key command like Escape. This SoPointingAction will receive no further calls of dragMoveTo or endPress until a new drag is started. The default implementation calls endPress to be compatible with SoPointingActions that don't implement this new method.

Definition at line 226 of file SoPointingAction.h.

◆ dragMoveTo()

virtual void SoPointingAction::dragMoveTo ( const SoPointerPosition & pos )

pure virtual

Continues the drag to given device position.

Implemented in SoOffsetPointingAction, SoCSODrawOnSurfaceDrawAction, CSOAbstractCreateAction, CSOBulgeAction, CSOInsertSeedPointIntoPathPointListAction, CSOLabelMoveAction, CSOLabelResizeAction, CSOSelectAndMoveAction, and CSOTransformAction.

◆ endPress()

virtual SoPointingAction * SoPointingAction::endPress ( int clickCount )

pure virtual

Ends the drag at last device position.

If this method returns a non-NULL SoPointingAction, the pointing device is restricted to this SoPointingAction until releaseGrab() is called or another call to endPress returns NULL. This is useful if the end user is required to click at at least one other position.

Note that locking of the returned action breaks down if the same node is used in several viewers, since each viewer usually has its own interaction controller that manages locked actions on its own.

Parameters

clickCount gives the number of clicks at the last start position. I.e. for a normal drag it is 0, for a single click it is 1, for a double click it is 2 and for a triple click it is 3. Note that for a clickCount greater zero you will not have received any dragMoveTo calls if wantsImmediateDragUpdates returns false.

Implemented in SoOffsetPointingAction, CSOAbstractCreateAction, CSOBulgeAction, CSOInsertSeedPointIntoPathPointListAction, CSOLabelMoveAction, CSOLabelResizeAction, CSOSelectAndMoveAction, CSOTransformAction, and SoCSODrawOnSurfaceDrawAction.

◆ getCurrentCursor()

virtual int SoPointingAction::getCurrentCursor ( SoViewerProxy * ) const

inlinevirtual

Returns the cursor ID to display for this action, as defined in SoViewerProxy.h - this gets (at least) called after setMode(), isSensitiveAt(), startPressAt(), dragMoveTo(), and endPress().

The SoViewerProxy pointer is provided so one can define own cursors when this method is called (see header file SoViewerProxy.h for instructions).

Reimplemented in SoCSODrawOnSurfaceDrawAction, CSOAbstractCreateAction, CSOBulgeAction, CSOInsertSeedPointIntoPathPointListAction, CSOLabelMoveAction, CSOLabelResizeAction, CSOSelectAndMoveAction, CSOTransformAction, and SoOffsetPointingAction.

Definition at line 166 of file SoPointingAction.h.

◆ getCurrentStatusMessage()

virtual std::string SoPointingAction::getCurrentStatusMessage ( ) const

inlinevirtual

Returns a status message for display in status bar (make it short!), this will get called at same time as getCurrentCursor.

Note: This is currently unused.

Reimplemented in SoOffsetPointingAction.

Definition at line 172 of file SoPointingAction.h.

◆ getNumModes()

virtual int SoPointingAction::getNumModes ( ) const

inlinevirtual

Returns the number of different modes this action has - modes can be changed during drag and handle drag restrictions or drag result.

Modes are normally controlled through the modifier keys.

Reimplemented in CSOAbstractCreateAction, CSOBulgeAction, and CSOSelectAndMoveAction.

Definition at line 158 of file SoPointingAction.h.

◆ getTriggers()

TriggerList SoPointingAction::getTriggers ( ) const

inline

Returns the list of default modifier/button mask combinations set for this action.

Definition at line 147 of file SoPointingAction.h.

◆ grabReleased()

void SoPointingAction::grabReleased ( )

Call this to release an interaction grab that has been established by the return value of endPress(), e.g., because it was aborted through a SoCommandAction.

◆ isPositionSensitive()

virtual bool SoPointingAction::isPositionSensitive ( ) const

inlinevirtual

Position sensitive actions can only start at positions where isSensitiveAt() return true.

Also they can't transition to other actions without releasing all mouse buttons. If this method returns false, isSensitiveAt() will not be called, since it is assumed to always return true.

You can set this flag from the constructor of this class.

Definition at line 131 of file SoPointingAction.h.

◆ isSensitiveAt()

virtual bool SoPointingAction::isSensitiveAt ( const SoPointerPosition & pos )

pure virtual

Returns true if the gesture is startable at the given device position.

If not, a mouse click will be handed to another SoPointingAction (and the cursor shape of this action is ignored)!

Note: Only called if isPositionSensitive() returns true.

Implemented in SoOffsetPointingAction, SoCSODrawOnSurfaceDrawAction, CSOAbstractCreateAction, CSOBulgeAction, CSOInsertSeedPointIntoPathPointListAction, CSOLabelMoveAction, CSOLabelResizeAction, CSOSelectAndMoveAction, and CSOTransformAction.

◆ proxiedOffsetAction()

virtual SoOffsetAction * SoPointingAction::proxiedOffsetAction ( ) const

inlineprotectedvirtual

Reimplemented in SoOffsetPointingAction.

Definition at line 261 of file SoPointingAction.h.

◆ releaseGrab()

virtual void SoPointingAction::releaseGrab ( StopMode )

inlinevirtual

This will be called by the controller if you should release the grab established by endPress.

The SoPointingAction should be aborted/finished. (This will not be called while dragging!) There is no need to call grabReleased().

Parameters

mode	how the grab should be released. See SoPointingAction::StopMode.

(Note: This is currently not implemented.)

Reimplemented in CSOInsertSeedPointIntoPathPointListAction, and CSOSelectAndMoveAction.

Definition at line 248 of file SoPointingAction.h.

◆ setHighlightAt()

virtual void SoPointingAction::setHighlightAt ( const SoPointerPosition & )

inlinevirtual

This method is called so that highlighting of objects under the mouse cursor can occur.

It is not called while dragging.

Definition at line 189 of file SoPointingAction.h.

◆ setMode()

virtual void SoPointingAction::setMode ( int )

inlinevirtual

This gets called if the mode was changed and before startPressAt is called.

Use this value to implement different dragging modes.

Note: You must override getNumModes() to return the number of required modes.

Reimplemented in CSOAbstractCreateAction, CSOBulgeAction, and CSOSelectAndMoveAction.

Definition at line 178 of file SoPointingAction.h.

◆ setTrigger() [1/2]

void SoPointingAction::setTrigger ( const Trigger & trigger )

Same with Trigger object.

◆ setTrigger() [2/2]

void SoPointingAction::setTrigger	(	int	triggerMask,
		int	ignoreMask = 0 )

Sets the (only) default modifier/button mask for triggering this action.

The modifier/button mask can be overridden through the controller.

Referenced by SoCSODrawOnSurfaceDrawAction::setTriggerMask().

◆ startPressAt()

virtual void SoPointingAction::startPressAt ( const SoPointerPosition & pos )

pure virtual

Starts a drag at given device position.

It is guaranteed that this will be followed by (possibly) dragMoveTo calls and either an endPress or dragCancelled call.

Implemented in SoOffsetPointingAction, SoCSODrawOnSurfaceDrawAction, CSOAbstractCreateAction, CSOBulgeAction, CSOInsertSeedPointIntoPathPointListAction, CSOLabelMoveAction, CSOLabelResizeAction, CSOSelectAndMoveAction, and CSOTransformAction.

◆ triggersAction()

virtual bool SoPointingAction::triggersAction ( int mask )

virtual

Returns whether the given modifier/button combination activates this action according to the default bindings.

Overrides from the interaction controller are ignored by this method.

◆ unsetHighlight()

virtual void SoPointingAction::unsetHighlight ( )

inlinevirtual

Remove any highlighting if this method is called.

This is called when another pointing action gets active or when the mouse cursor has left the window.

Definition at line 194 of file SoPointingAction.h.

◆ wantsImmediateDragUpdates()

virtual bool SoPointingAction::wantsImmediateDragUpdates ( )

inlinevirtual

Let this method return false if you don't want dragMoveTo to be called until it is clear that the interaction will not be handled as a click (endPress will be called with a clickCount greater zero).

This can improve the user experience.

This should probably be overridden to return false if you use the clickCount parameter of endPress.

Definition at line 256 of file SoPointingAction.h.

◆ wantsMouseOverUpdates()

virtual bool SoPointingAction::wantsMouseOverUpdates ( )

inlinevirtual

Override this to return true if this action should get location updates directly before rendering, so it can update its status.

The cursor position might be the same as in previous calls, which is normally avoided.

This is only interesting for the interactions of special Inventor nodes like those derived from SoView2DExtension, where additional position information is passed in SoPointerPosition. This information may change depending on the state of the SoView2D, even if the cursor position does not.

Reimplemented in CSOSelectAndMoveAction.

Definition at line 236 of file SoPointingAction.h.

Friends And Related Symbol Documentation

◆ SoInteractionCoordinator

friend class SoInteractionCoordinator

friend

Definition at line 90 of file SoPointingAction.h.

◆ SoOffsetPointingAction

friend class SoOffsetPointingAction

friend

Definition at line 91 of file SoPointingAction.h.

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

MeVis/Foundation/Sources/SoManagedInteraction/SoPointingAction.h

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Trigger

◆ TriggerList

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

◆ StopMode

Constructor & Destructor Documentation

◆ SoPointingAction()

Member Function Documentation

◆ addTrigger()

◆ clearTriggers()

◆ dragCancelled()

◆ dragMoveTo()

◆ endPress()

◆ getCurrentCursor()

◆ getCurrentStatusMessage()

◆ getNumModes()

◆ getTriggers()

◆ grabReleased()

◆ isPositionSensitive()

◆ isSensitiveAt()

◆ proxiedOffsetAction()

◆ releaseGrab()

◆ setHighlightAt()

◆ setMode()

◆ setTrigger() [1/2]

◆ setTrigger() [2/2]

◆ startPressAt()

◆ triggersAction()

◆ unsetHighlight()

◆ wantsImmediateDragUpdates()

◆ wantsMouseOverUpdates()

Friends And Related Symbol Documentation

◆ SoInteractionCoordinator

◆ SoOffsetPointingAction