TSLInteractionMode Class Reference

Inheritance diagram for TSLInteractionMode:

Detailed Description

This is the base class for a simple interaction mode handling system. This allows the various interaction modes such as zoom and pan to be implemented in an encapsulated and operating system independent manner.

The user's application creates an instance of one the TSLInteractionMode derived classes and passes it to an instance of a TSLInteractionModeManager derived class. The 'm_display' attribute of this base class provides access to useful methods for interacting and querying the drawing surface to which the mode is attached. It also provides basic echo rectangle and line handling.

When the application wants to activate this mode, it passes the id to the mode manager. All subsequent mouse events are passed to the mode - until it is replaced by another. When a mode becomes active, the 'activate' method is triggered. When a mode becomes inactive, the 'deactivate' method is triggered. The mode event handlers typically return true to indicate that the view should be redrawn.

Any derived mode should ensure that the 'viewChanged' method and 'resetMode' methods are triggered when the view has been changed, or when the current mode has finished and should be reset to the default mode.

Some event handlers have specific default behaviours. See individual handlers for further details. Most other handlers in this base class return false to indicate that no redraw is required. In the derived classes, only those locator methods that are actually useful need to be overridden.

Note: If you are not using the same version of the compiler that MapLink was built with then any user derived classes that have been added to a TSLInteractionModeManager through the addMode() method should be removed from the mode manager before the manager is deleted in order to ensure memory is freed using the correct heap.

Public Member Functions
virtual	~TSLInteractionMode ()
virtual void	activate ()
virtual void	deactivate ()
virtual void	onDraw (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2)
virtual bool	onLButtonDown (TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control)
virtual bool	onLButtonUp (TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control)
virtual bool	onMButtonDown (TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control)
virtual bool	onMButtonUp (TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control)
virtual bool	onMouseMove (TSLButtonType button, TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control)
virtual bool	onMouseWheel (short delta, TSLDeviceUnits x, TSLDeviceUnits y, int zoomPercentage, bool lockCursorLocation)
virtual bool	onRButtonUp (TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control)
virtual bool	onRButtonDown (TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control)
virtual bool	onGestureZoom (TSLDeviceUnits cx, TSLDeviceUnits cy, double zoomFactor)
virtual bool	onGesturePan (TSLDeviceUnits startx, TSLDeviceUnits starty, TSLDeviceUnits endx, TSLDeviceUnits endy)
virtual bool	onGestureRotate (TSLDeviceUnits cx, TSLDeviceUnits cy, double dblAngle)
virtual bool	onGestureTap (TSLDeviceUnits x, TSLDeviceUnits y)
virtual bool	onGesturePressAndTap (TSLDeviceUnits firstFingerX, TSLDeviceUnits firstFingerY, long lDelta)
virtual bool	onGestureTwoFingerTap (TSLDeviceUnits cx, TSLDeviceUnits cy)
virtual void	onSize (TSLDeviceUnits cx, TSLDeviceUnits cy)
virtual TSLCursorStyle	queryCursor ()
virtual const char *	queryPrompt ()
virtual void	setDisplay (TSLInteractionModeDisplay *display)
int	id ()

Protected Member Functions
	TSLInteractionMode (int modeID, bool middleButtonPansToPoint=true)

Protected Attributes
int	m_id
TSLDrawingSurface *	m_drawingSurface
bool	m_middleButtonPansToPoint
TSLInteractionModeDisplay *	m_display

Constructor & Destructor Documentation

~TSLInteractionMode()

virtual TSLInteractionMode::~TSLInteractionMode ( )

virtual

Virtual destructor for the base Interaction mode class.

TSLInteractionMode()

TSLInteractionMode::TSLInteractionMode ( int modeID, bool middleButtonPansToPoint = true )

protected

Protected constructor for interaction mode base class. Protected to prevent instantiation of the base class.

Parameters

modeID	This ID is not used by the mode itself, but is used as a unique identified by the mode manager.
middleButtonPansToPoint	Defaults to true. This flag allows modes to easily provide standard behaviour for pressing the middle button - typically the mouse wheel.

Member Function Documentation

activate()

virtual void TSLInteractionMode::activate ( )

virtual

This method is triggered when a mode is activated by the user - and therefore becomes the current mode.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, TSLInteractionModeMagnify, TSLInteractionModePan, and TSLInteractionModeZoom.

deactivate()

virtual void TSLInteractionMode::deactivate ( )

virtual

This method is triggered when a mode is deactivated by the user - and therefore is no longer the current mode.

The derived class should clear any echo lines that may be active and generally tidy up after itself.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, TSLInteractionModeMagnify, TSLInteractionModePan, and TSLInteractionModeZoom.

id()

int TSLInteractionMode::id ( )

inline

Query the unique id passed in the constructor.

onDraw()

virtual void TSLInteractionMode::onDraw ( TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2 )

virtual

Event handler for the paint method.

The default handler does nothing.

Parameters

(x1,y1)	Bottom left, in device units, of the area being redrawn.
(x2,y2)	Top right, in device units, of the area being redrawn.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeMagnify, and TSLInteractionModeZoom.

onGesturePan()

virtual bool TSLInteractionMode::onGesturePan ( TSLDeviceUnits startx, TSLDeviceUnits starty, TSLDeviceUnits endx, TSLDeviceUnits endy )

virtual

Gesture handler for interaction modes.

The default implementation drags the view as requested and returns true.

Parameters

(startx,starty)	Position of start of the drag gesture, in device unit coordinates.
(endx,endy)	Position of end of the drag gesture, in device unit coordinates.

Returns

true if the view needs to be redrawn, false otherwise.

onGesturePressAndTap()

virtual bool TSLInteractionMode::onGesturePressAndTap ( TSLDeviceUnits firstFingerX, TSLDeviceUnits firstFingerY, long lDelta )

virtual

Gesture handler for interaction modes.

The default implementation calls onLButtonDown.

Parameters

(firstFingerX,firstFingerY)	Location of the press, in device unit coordinates.
lDelta	Distance of the tap from the press, in device units

Returns

true if the view needs to be redrawn, false otherwise.

onGestureRotate()

virtual bool TSLInteractionMode::onGestureRotate ( TSLDeviceUnits cx, TSLDeviceUnits cy, double dblAngle )

virtual

Gesture handler for interaction modes.

The default implementation rotates the view as requested and returns true.

Parameters

(cx,cy)	Centre of the rotate gesture, in device unit coordinates.
(dblAngle)	Angle to set the drawing surface rotation to.

Returns

true if the view needs to be redrawn, false otherwise.

onGestureTap()

virtual bool TSLInteractionMode::onGestureTap ( TSLDeviceUnits x, TSLDeviceUnits y )

virtual

Gesture handler for interaction modes.

The default implementation calls onLButtonDown.

Parameters

(x,y)

Location of the tap, in device unit coordinates.

Returns

true if the view needs to be redrawn, false otherwise.

onGestureTwoFingerTap()

virtual bool TSLInteractionMode::onGestureTwoFingerTap ( TSLDeviceUnits cx, TSLDeviceUnits cy )

virtual

Gesture handler for interaction modes.

The default implementation resets the view and returns true.

Parameters

(cx,cy)

Location of the centre of the tap, in device unit coordinates.

Returns

true if the view needs to be redrawn, false otherwise.

onGestureZoom()

virtual bool TSLInteractionMode::onGestureZoom ( TSLDeviceUnits cx, TSLDeviceUnits cy, double zoomFactor )

virtual

Gesture handler for interaction modes.

The default implementation zooms in by the specified zoomFactor, maintaining the location of the specified location, and returns true.

Parameters

(cx,cy)	Position of centre of the zoom pinch event, in device unit coordinates.
zoomFactor	Scaling factor to apply to current view

Returns

true if the view needs to be redrawn, false otherwise.

onLButtonDown()

virtual bool TSLInteractionMode::onLButtonDown ( TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control )

virtual

Locator handler for interaction modes.

The default base implementation returns false.

Parameters

(x,y)	Position of locator event, in device unit coordinates.
shift	Flag to indicate whether the shift key is pressed. An interaction mode may use this to modify its behaviour.
control	Flag to indicate whether the control key is pressed. An interaction mode may use this to modify its behaviour.

Returns

true if the view needs to be redrawn, false otherwise.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, TSLInteractionModePan, and TSLInteractionModeZoom.

onLButtonUp()

virtual bool TSLInteractionMode::onLButtonUp ( TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control )

virtual

Locator handler for interaction modes.

The default base implementation returns false.

Parameters

(x,y)	Position of locator event, in device unit coordinates.
shift	Flag to indicate whether the shift key is pressed. An interaction mode may use this to modify its behaviour.
control	Flag to indicate whether the control key is pressed. An interaction mode may use this to modify its behaviour.

Returns

true if the view needs to be redrawn, false otherwise.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, and TSLInteractionModeZoom.

onMButtonDown()

virtual bool TSLInteractionMode::onMButtonDown ( TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control )

virtual

Locator handler for interaction modes.

The default base implementation pans to the click position and returns true if the pan was successful. This behaviour occurs if the constructor was passed the appropriate flag.

Parameters

(x,y)	Position of locator event, in device unit coordinates.
shift	Flag to indicate whether the shift key is pressed. An interaction mode may use this to modify its behaviour.
control	Flag to indicate whether the control key is pressed. An interaction mode may use this to modify its behaviour.

Returns

true if the view needs to be redrawn, false otherwise.

Reimplemented in TSLInteractionModeEdit.

onMButtonUp()

virtual bool TSLInteractionMode::onMButtonUp ( TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control )

virtual

Locator handler for interaction modes.

The default base implementation returns false.

Parameters

(x,y)	Position of locator event, in device unit coordinates.
shift	Flag to indicate whether the shift key is pressed. An interaction mode may use this to modify its behaviour.
control	Flag to indicate whether the control key is pressed. An interaction mode may use this to modify its behaviour.

Returns

true if the view needs to be redrawn, false otherwise.

Reimplemented in TSLInteractionModeEdit.

onMouseMove()

virtual bool TSLInteractionMode::onMouseMove ( TSLButtonType button, TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control )

virtual

Mouse move handlers for interaction mode base class

The default base class implementations all do nothing and return false.

Parameters

button	Type of button pressed, if any.
(x,y)	Position of locator event, in device unit co-ordinates.
shift	Flag to indicate whether the shift key is pressed. An interaction mode may use this to modify its behaviour.
control	Flag to indicate whether the control key is pressed. An interaction mode may use this to modify its behaviour.

Returns

true if the view needs to be redrawn, false otherwise. The default base class implementations all return false.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, TSLInteractionModeMagnify, and TSLInteractionModeZoom.

onMouseWheel()

virtual bool TSLInteractionMode::onMouseWheel ( short delta, TSLDeviceUnits x, TSLDeviceUnits y, int zoomPercentage, bool lockCursorLocation )

virtual

Mouse wheel hander for interaction modes.

The default behaviour of this is to zoom in or out by the percentage passed to the constructor. A positive value of delta is a zoom-in, a negative value of delta is a zoom-out. This behaviour can be overridden by derived classes.

Parameters

delta	Delta value of mouse wheel movement. See Windows help for further information.
(x,y)	Position of locator event, in device unit coordinates.
zoomPercentage	Percentage of view to zoom in/out
lockCursorLocation	If true, then lock to cursor location at the same place on the screen, otherwise zoom in around the centre of the current view. Requires the specific point to be in client window space not in screen space.

Returns

true if the view needs to be redrawn, false otherwise.

onRButtonDown()

virtual bool TSLInteractionMode::onRButtonDown ( TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control )

virtual

Locator handler for interaction modes.

The default base implementation returns false.

Parameters

(x,y)	Position of locator event, in device unit coordinates.
shift	Flag to indicate whether the shift key is pressed. An interaction mode may use this to modify its behaviour.
control	Flag to indicate whether the control key is pressed. An interaction mode may use this to modify its behaviour.

Returns

true if the view needs to be redrawn, false otherwise.

Reimplemented in TSLInteractionModeEdit.

onRButtonUp()

virtual bool TSLInteractionMode::onRButtonUp ( TSLDeviceUnits x, TSLDeviceUnits y, bool shift, bool control )

virtual

Locator handler for interaction modes.

The default base implementation returns false.

Parameters

(x,y)	Position of locator event, in device unit coordinates.
shift	Flag to indicate whether the shift key is pressed. An interaction mode may use this to modify its behaviour.
control	Flag to indicate whether the control key is pressed. An interaction mode may use this to modify its behaviour.

Returns

true if the view needs to be redrawn, false otherwise.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, TSLInteractionModeMagnify, TSLInteractionModePan, and TSLInteractionModeZoom.

onSize()

virtual void TSLInteractionMode::onSize ( TSLDeviceUnits cx, TSLDeviceUnits cy )

virtual

Event handler for the size method.

This default handler does nothing.

Parameters

cx	New width of drawing surface.
cy	New height of drawing surface.

Reimplemented in TSLInteractionModeMagnify.

queryCursor()

virtual TSLCursorStyle TSLInteractionMode::queryCursor ( )

virtual

Query the cursor style that may be appropriate to the currently active mode.

Returns TSLCursorStyleNone if no particular cursor style is appropriate. This is also the default return value if the method is not overridden.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, TSLInteractionModeMagnify, TSLInteractionModePan, and TSLInteractionModeZoom.

queryPrompt()

virtual const char * TSLInteractionMode::queryPrompt ( )

virtual

Query prompt to display for this mode.

The default implementation returns an empty string. It is up to the derived modes to decide what prompt to return.

Reimplemented in TSLInteractionModeEdit, TSLInteractionModeGrab, TSLInteractionModeMagnify, TSLInteractionModePan, and TSLInteractionModeZoom.

setDisplay()

virtual void TSLInteractionMode::setDisplay ( TSLInteractionModeDisplay * display )

virtual

Internal function called by the mode manager to bind an instance of TSLInteractionModeDisplay to the mode.

Reimplemented in TSLInteractionModeEdit, and TSLInteractionModeMagnify.

Member Data Documentation

m_display

TSLInteractionModeDisplay* TSLInteractionMode::m_display

protected

Initialised by the 'setDisplay' method. Use this to gain access to useful queries and simple echo handling.

m_drawingSurface

TSLDrawingSurface* TSLInteractionMode::m_drawingSurface

protected

pointer to drawing surface being used. Initialised in the setDisplay method.

m_id

int TSLInteractionMode::m_id

protected

Id of this mode, initialised by the constructor.

m_middleButtonPansToPoint

bool TSLInteractionMode::m_middleButtonPansToPoint

protected

Flag to indicate to the default middle button handler whether to perform the default pan-to-point behaviour.