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. More...

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

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 subtypes of this class. More...

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

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

void	clearTriggers ()
	Removes all triggers. More...

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

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

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

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

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

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

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(). More...

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

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

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

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

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

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

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

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

virtual void	dragCancelled ()
	This is called if the current drag operation is canceled, e.g., through a key command like Escape. More...

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

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. More...

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

virtual bool	wantsImmediateDragUpdates ()
	Let this method return `false` if you do not 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). More...

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

virtual	~SoInteraction ()
	Virtual destructor. More...

SoInteractionOwner *	getOwner () const
	Returns the interaction provider of this entry. More...

virtual bool	isEnabled () const
	Returns the enabled status of this interaction - if this returns `false`, the action is not selectable (but if a mouse action has already been started, it will not be aborted if this returns `false`). More...

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

std::string	getID () const
	Returns the ID of this interaction. More...

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

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

InteractionType	getInteractionType () const
	Returns type of interaction object. More...

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

int	getMenuPriority () const

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

virtual std::string	getUserName () const
	Returns user-visible name of this item for direct display (e.g., in tool box or menu). More...

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

virtual std::string	getIconFile () const
	Returns the filename of an icon (e.g., for use in a tool box or in menu). More...

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

virtual std::string	getDescription () const
	Returns the description for user help. More...

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

virtual void	ref ()

virtual void	unref ()

int	getStateVersion () const

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

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 will still keep track of the SoPointingAction that would get activated if the left mouse button were 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 becomes a 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 differently. This flag, which can be set from the constructor, is meant to mark position specific actions. If this flag is not set, it marks mouse interactions that 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 are 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:

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

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

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	The SoInteractionOwner to which the action is added. Ownership is automatically transferred, you do not need to free this object.
id	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

Removes 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 canceled, 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 do not implement this new method.

Definition at line 226 of file SoPointingAction.h.

References SoOffsetPointingAction::endPress().

◆ dragMoveTo()

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

pure virtual

Continues the drag to given device position.

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

◆ 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. This is, 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 than zero, you will not have received any dragMoveTo calls if wantsImmediateDragUpdates returns false.

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

◆ 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 custom cursors when this method is called (see header file SoViewerProxy.h for instructions).

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

Definition at line 166 of file SoPointingAction.h.

◆ getCurrentStatusMessage()

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

inlinevirtual

Returns a status message for display in the status bar of MeVisLab (make it short!), this is 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 of this action - modes can be changed during drag, and handle drag restrictions or drag result.

Modes are normally controlled through the modifier keys.

Reimplemented in CSOSelectAndMoveAction, CSOBulgeAction, and CSOAbstractCreateAction.

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 cannot 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.

Otherwise, 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 CSOTransformAction, CSOSelectAndMoveAction, CSOLabelResizeAction, CSOLabelMoveAction, CSOInsertSeedPointIntoPathPointListAction, CSOBulgeAction, CSOAbstractCreateAction, SoCSODrawOnSurfaceDrawAction, and SoOffsetPointingAction.

◆ 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 CSOSelectAndMoveAction, and CSOInsertSeedPointIntoPathPointListAction.

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 CSOSelectAndMoveAction, CSOBulgeAction, and CSOAbstractCreateAction.

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 CSOTransformAction, CSOSelectAndMoveAction, CSOLabelResizeAction, CSOLabelMoveAction, CSOInsertSeedPointIntoPathPointListAction, CSOBulgeAction, CSOAbstractCreateAction, SoCSODrawOnSurfaceDrawAction, and SoOffsetPointingAction.

◆ 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

Removes 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 do not 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 positional information is passed in SoPointerPosition. This information may change depending on the state of the SoView2D, even if the cursor position does not change.

Reimplemented in CSOSelectAndMoveAction.

Definition at line 236 of file SoPointingAction.h.

Friends And Related Function 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 Function Documentation

◆ SoInteractionCoordinator

◆ SoOffsetPointingAction