Inheritance diagram for TSL3DInteractionModeManager:

[legend]

Detailed Description

This is the base class for a simple 3D interaction mode handling system. This allows the various interaction modes such as zoom and pan to be managed and implemented in an encapsulated and operating system independent manner. In addition, it maintains an optional view stack for a history of viewing positions, and an array of optional saved positions which may be set by the user.

The user's application creates an instance of one the TSL3DInteractionModeManager derived classes, passing in a callback handler - derived from TSL3DInteractionModeRequest. All mouse, draw and size events must be forwarded to the manager, along with all view modification requests. These methods will typically return true if the view has changed and needs to be redrawn, or false if the view has not changed. In addition to this return value, the viewChanged callback will be triggered if the view has changed.

Operating system dependent code such as echo rectangle drawing, is encapsulated in the objects derived from the virtual base class TSL3DInteractionModeManager and TSL3DInteractionModeDisplay. The TSL3DInteraction ModeManager instance will create the appropriate version of the TSL3DInteractionModeDisplay class for internal use by the interaction modes.

The application should create instances of individual TSL3DInteractionMode derived classes and pass these in using the addMode method. A default mode may be nominated which will be activated when other modes are inactive. This is typically an editing mode.

Deprecated: Deprecated as of MapLink 11.1. Advised to use MapLink Earth SDK instead.

Public Member Functions
virtual	~TSL3DInteractionModeManager ()

bool	addMode (TSL3DInteractionMode *mode, bool isDefault)

TSLDeviceUnits	getCurrentMode (TSL3DInteractionMode **mode=0) const

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)

bool	onMouseWheel (short delta, TSLDeviceUnits x, TSLDeviceUnits y)

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

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

void	onSize (TSLDeviceUnits cx, TSLDeviceUnits cy)

TSLCursorStyle	queryCursor ()

const char *	queryPrompt ()

TSL3DInteractionMode *	removeMode (TSLDeviceUnits id)

void	resetMode (TSLButtonType button, TSLDeviceUnits x, TSLDeviceUnits y)

bool	resetToView (const TSL3DCameraPosition &cameraPosition, bool addToViewStack=true)

bool	resetToDefaultView (bool addToViewStack=true)

void	resetViews ()

bool	savedViewGoto (int idx)

bool	savedViewReset ()

bool	savedViewSetToCurrent (int idx)

bool	savedViewValid (int idx)

bool	setCurrentMode (TSLDeviceUnits id)

bool	setDefaultView ()

bool	setDefaultMode (TSLDeviceUnits id)

bool	setViewedExtent (const TSL3DCameraPosition &cameraPosition, bool addToViewStack=true)

void	viewChanged (bool addToViewStack)

bool	viewStackGetCurrent (TSL3DCameraPosition &cameraPosition)

bool	viewStackGotoNext ()

bool	viewStackGotoPrevious ()

bool	viewStackNextValid ()

bool	viewStackPreviousValid ()

bool	viewStackReset ()

int	viewStackSize ()

bool	savedViewGet (int idx, TSL3DCameraPosition &cameraPosition)

bool	savedViewSet (int idx, const TSL3DCameraPosition &cameraPosition)

bool	zoomIn (int zoomPercentage, bool addToViewStack=true)

bool	zoomOut (int zoomPercentage, bool addToViewStack=true)

bool	setElevation (double elevation, bool addToViewStack)

bool	setRotation (double rotation, bool addToViewStack)

Protected Member Functions
	TSL3DInteractionModeManager (TSL3DInteractionModeRequest *requestHandler, int maxViewStackSize=5, int numSavedViews=5)

TSL3DCameraPosition	getCameraPosition ()

bool	setCameraPosition (const TSL3DCameraPosition &cameraPosition)

Protected Attributes
TSL3DInteractionModeDisplay *	m_display

TSL3DInteractionCameraManager *	m_cameraManager

Constructor & Destructor Documentation

◆ ~TSL3DInteractionModeManager()

virtual TSL3DInteractionModeManager::~TSL3DInteractionModeManager ( )

virtual

Destructor.

◆ TSL3DInteractionModeManager()

TSL3DInteractionModeManager::TSL3DInteractionModeManager	(	TSL3DInteractionModeRequest *	requestHandler,
		int	maxViewStackSize = 5,
		int	numSavedViews = 5 )

protected

Member Function Documentation

◆ addMode()

bool TSL3DInteractionModeManager::addMode	(	TSL3DInteractionMode *	mode,
		bool	isDefault )

Adds a mode to the list managed by this TSL3DInteractionModeManager.

The TSL3DInteractionModeManager assumes ownership of the mode, which will be destroyed when the manager instance is deleted.

Parameters

mode	Instance of mode class to use. The id property of the mode must be unique and non-zero.
isDefault	Flag indicating whether this mode is to be used as the default. The last mode added with this flag becomes the default mode. The default mode is activated when no other mode has been chosen. If no mode is made the default then any subsequent mouse actions will be ignored until a mode is activated.

Returns: true on success, false otherwise.

◆ getCameraPosition()

TSL3DCameraPosition TSL3DInteractionModeManager::getCameraPosition ( )

protected

◆ getCurrentMode()

TSLDeviceUnits TSL3DInteractionModeManager::getCurrentMode ( TSL3DInteractionMode ** mode = 0 ) const

Query the id and instance of the currently active mode.

Returns by value the id property if the currently active mode, 0 if no mode is currently active.

Returns by reference the mode instance.

◆ onDraw()

void TSL3DInteractionModeManager::onDraw	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		TSLDeviceUnits	x2,
		TSLDeviceUnits	y2 )

Event handler for the paint method. This event will be passed on to the currently active mode.

This must be called in the paint (OnDraw) handler of the application, after the MapLink drawing surface has been rendered. This is used to draw any dynamic echo lines or other objects such as the magnifying glass.

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.

◆ onLButtonDown()

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

virtual

Locator handler for interaction modes. This event will be passed on to the currently active mode.

NOTE : On Windows, an mfc application automatically uses a window class that traps double click events and sends them to the On?ButtonDblClick handler. It may be necessary to redirect these to the On?ButtonDown handler to avoid losing some interactions

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.

◆ onLButtonUp()

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

virtual

Locator handler for interaction modes. This event will be passed on to the currently active mode.

NOTE : On Windows, an mfc application automatically uses a window class that traps double click events and sends them to the On?ButtonDblClick handler. It may be necessary to redirect these to the On?ButtonDown handler to avoid losing some interactions

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.

◆ onMButtonDown()

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

virtual

Locator handler for interaction modes. This event will be passed on to the currently active mode.

NOTE : On Windows, an mfc application automatically uses a window class that traps double click events and sends them to the On?ButtonDblClick handler. It may be necessary to redirect these to the On?ButtonDown handler to avoid losing some interactions

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.

◆ onMButtonUp()

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

virtual

Locator handler for interaction modes. This event will be passed on to the currently active mode.

NOTE : On Windows, an mfc application automatically uses a window class that traps double click events and sends them to the On?ButtonDblClick handler. It may be necessary to redirect these to the On?ButtonDown handler to avoid losing some interactions

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.

◆ onMouseMove()

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

virtual

Mouse move handler for interaction modes. This event will be passed on to the currently active mode.

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.

◆ onMouseWheel()

bool TSL3DInteractionModeManager::onMouseWheel	(	short	delta,
		TSLDeviceUnits	x,
		TSLDeviceUnits	y )

Mouse wheel hander for interaction modes. This event will be passed on to the currently active mode.

Parameters

delta	Delta value of mouse wheel movement. See Windows help for further information.
(x,y)	Position of locator event, in device unit coordinates.

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

◆ onRButtonDown()

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

virtual

Locator handler for interaction modes. This event will be passed on to the currently active mode.

NOTE : On Windows, an mfc application automatically uses a window class that traps double click events and sends them to the On?ButtonDblClick handler. It may be necessary to redirect these to the On?ButtonDown handler to avoid losing some interactions

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.

◆ onRButtonUp()

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

virtual

Locator handler for interaction modes. This event will be passed on to the currently active mode.

NOTE : On Windows, an mfc application automatically uses a window class that traps double click events and sends them to the On?ButtonDblClick handler. It may be necessary to redirect these to the On?ButtonDown handler to avoid losing some interactions

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.

◆ onSize()

void TSL3DInteractionModeManager::onSize	(	TSLDeviceUnits	cx,
		TSLDeviceUnits	cy )

Event handler for the size method. This event will be passed on to the currently active mode.

This must be called in the size (OnSize) handler of the application, after the MapLink drawing surface has been resized. This is used to draw any dynamic echo lines or other objects such as the magnifying glass.

Parameters

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

◆ queryCursor()

TSLCursorStyle TSL3DInteractionModeManager::queryCursor ( )

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

Returns TSLCursorStyleNone if no particular cursor style is appropriate, cursor style otherwise.

◆ queryPrompt()

const char * TSL3DInteractionModeManager::queryPrompt ( )

Query prompt to display for currently active mode.

◆ removeMode()

TSL3DInteractionMode * TSL3DInteractionModeManager::removeMode ( TSLDeviceUnits id )

This method removes the specified mode from the manager, returning ownership back to the application.

Parameters

id	ID of mode to remove

Returns: mode instance, NULL if mode not found.

◆ resetMode()

void TSL3DInteractionModeManager::resetMode	(	TSLButtonType	button,
		TSLDeviceUnits	x,
		TSLDeviceUnits	y )

Force reset to default mode (if any)

This method is called by the TSLInteractionModes when they should deactivate, but it may also be called by an application to make the manager revert to the default operation. The manager will subsequently trigger the 'resetMode' callback in the TSLInteractionModeRequest object.

Parameters

button	Button pressed which triggered deactivation (if any)
(x,y)	If button pressed to trigger deactivation, location in device coordinates of press.

Request to set the view to a specified cameraPosition

This may typically be used to define a start position from a previous session.

Parameters

cameraPosition	cameraPosition to reset to.
addToViewStack	Defaults true. Flag to indicate whether this camera Position should be added to the view stack.

Returns: true if the view should be redrawn, false otherwise.

◆ resetToDefaultView()

bool TSL3DInteractionModeManager::resetToDefaultView ( bool addToViewStack = true )

Request to set the view to display the default extent.

Parameters

addToViewStack Defaults true. Flag to indicate whether this camera Position should be added to the view stack.

Returns: true if the view should be redrawn, false otherwise.

◆ resetToView()

bool TSL3DInteractionModeManager::resetToView	(	const TSL3DCameraPosition &	cameraPosition,
		bool	addToViewStack = true )

Request to set the view to a the specified position

Parameters

cameraPosition	View to set.
addToViewStack	Defaults true. Flag to indicate whether this camera Position should be added to the view stack.

Returns: true if the view should be redrawn, false otherwise.

◆ resetViews()

void TSL3DInteractionModeManager::resetViews ( )

This method clears all saved views and the view stack. It should be called when these become invalid. For example, if a new map is loaded with a different coordinate system.

◆ savedViewGet()

bool TSL3DInteractionModeManager::savedViewGet	(	int	idx,
		TSL3DCameraPosition &	cameraPosition )

Query the cameraPosition of a saved view.

If the view has not been saved, or an invalid index is passed, then this method returns false.

Parameters

idx	Index of saved view to query. The index is zero-based.
cameraPosition	Storage for returned view.

Returns: by reference the specified saved view Returns true if the returned cameraPosition is valid, false otherwise.

◆ savedViewGoto()

bool TSL3DInteractionModeManager::savedViewGoto ( int idx )

Change the current view to the specified saved view.

If the view has not been saved, or an invalid index is passed, then this method returns false.

Parameters

idx	Index of saved view to go toThe index is zero-based.

Returns: true if the view should be redrawn, false otherwise.

◆ savedViewReset()

bool TSL3DInteractionModeManager::savedViewReset ( )

Clears all saved views.

Returns true if successful, false otherwise. Failure typically occurs only if the saved view array was not initialised properly.

◆ savedViewSet()

bool TSL3DInteractionModeManager::savedViewSet	(	int	idx,
		const TSL3DCameraPosition &	cameraPosition )

Set the specified saved view to be the specified cameraPosition.

If the view cannot be saved, or an invalid index is passed, then this method returns false.

This may typically be used to help store the saved views across sessions.

Parameters

idx	Index of saved view to store into. The index is zero-based.
cameraPosition	cameraPosition to save.

Returns: true if the view was stored successfully.

should be added to the view stack.

Returns true if the zoom was successful and the view should be redrawn, false otherwise.

◆ savedViewSetToCurrent()

bool TSL3DInteractionModeManager::savedViewSetToCurrent ( int idx )

Set the specified saved view to be the current view of the attached drawing surface.

If the view has cannot been saved, or an invalid index is passed, then this method returns false.

Parameters

idx	Index of saved view to store into. The index is zero-based.

Returns: true if the view was stored successfully.

◆ savedViewValid()

bool TSL3DInteractionModeManager::savedViewValid ( int idx )

Query if the specified saved view has been used.

If the view has not been saved, or an invalid index is passed, then this method returns false.

This method is typically used for GUI status updates.

Parameters

idx	Index of saved view to query. The index is zero-based.

Returns: true if the view is valid and can there be used in savedViewGoto.

◆ setCameraPosition()

bool TSL3DInteractionModeManager::setCameraPosition ( const TSL3DCameraPosition & cameraPosition )

protected

◆ setCurrentMode()

bool TSL3DInteractionModeManager::setCurrentMode ( TSLDeviceUnits id )

Sets the current mode to that specified.

If a different mode is active, then it is deactivated before the specified mode is activated.

Parameters

id	Id property of the mode to activate. This is passed in the constructor of the mode and must be unique.

Returns: true if the mode was successfully activated, false otherwise.

Returns true if successful, false otherwise.

◆ setDefaultMode()

bool TSL3DInteractionModeManager::setDefaultMode ( TSLDeviceUnits id )

Allows the application to set the default mode.

Parameters

id	ID of mode to set as the new default

◆ setDefaultView()

bool TSL3DInteractionModeManager::setDefaultView ( )

Sets the current view to be the default extent

◆ setElevation()

bool TSL3DInteractionModeManager::setElevation	(	double	elevation,
		bool	addToViewStack )

Set current view elevation/tilt in degrees, +ve up.

◆ setRotation()

bool TSL3DInteractionModeManager::setRotation	(	double	rotation,
		bool	addToViewStack )

Set current rotation, in degrees, +ve clockwise.

◆ setViewedExtent()

bool TSL3DInteractionModeManager::setViewedExtent	(	const TSL3DCameraPosition &	cameraPosition,
		bool	addToViewStack = true )

Request to set the view to a specified cameraPosition.

This may be used to define a start position from a previous session, or to zoom to some other defined area - such as the data cameraPosition. This method is a synonym for resetTocameraPosition.

Parameters

cameraPosition	cameraPosition to reset to.
addToViewStack	Defaults true. Flag to indicate whether this camera Position should be added to the view stack.

Returns: true if the view should be redrawn, false otherwise.

◆ viewChanged()

void TSL3DInteractionModeManager::viewChanged ( bool addToViewStack )

Triggered by the currently active mode to indicate that the view has changed.

This will be passed on to the TSLInteractionModeRequest handler

Parameters

addToViewStack Flag to indicate whether the current view of the drawing surface should be added to the view stack.

◆ viewStackGetCurrent()

bool TSL3DInteractionModeManager::viewStackGetCurrent ( TSL3DCameraPosition & cameraPosition )

Query for the current cameraPosition from the view stack. This is normally the same as the current view of the drawing surface.

Parameters

cameraPosition Storage to return the cameraPosition.

Returns: by reference the current cameraPosition. Returns true if the returned cameraPosition is valid, false otherwise.

◆ viewStackGotoNext()

bool TSL3DInteractionModeManager::viewStackGotoNext ( )

This method updates the current view of the drawing surface to the next entry in the view stack, and moves the view stack cursor to the next item.

This method returns false if the view stack cursor is at the end of the stack.

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

◆ viewStackGotoPrevious()

bool TSL3DInteractionModeManager::viewStackGotoPrevious ( )

This method updates the current view of the drawing surface to the previous entry in the view stack, and moves the view stack cursor to the previous item.

This method returns false if the view stack cursor is at the end of the stack.

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

◆ viewStackNextValid()

bool TSL3DInteractionModeManager::viewStackNextValid ( )

This method queries whether it is possible to go to the next entry in the view stack.

This method is typically used for GUI status updates for calls to viewStack GotoNext.

Returns false if the view stack cursor is at the end of the stack, true otherwise.

◆ viewStackPreviousValid()

bool TSL3DInteractionModeManager::viewStackPreviousValid ( )

This method queries whether it is possible to go to the previous entry in the view stack.

This method is typically used for GUI status updates for calls to viewStack GotoPrevious

Returns false if the view stack cursor is at the end of the stack, true otherwise.

◆ viewStackReset()

bool TSL3DInteractionModeManager::viewStackReset ( )

Clears all entries from the view stack.

Returns true if successful, false otherwise. Failure typically occurs only if the view stack was not initialised properly.

◆ viewStackSize()

int TSL3DInteractionModeManager::viewStackSize ( )

Returns the current number of entries in the view stack. This number may be limited by specifying the upper limit in the constructor of this object.

◆ zoomIn()

bool TSL3DInteractionModeManager::zoomIn	(	int	zoomPercentage,
		bool	addToViewStack = true )

Zoom in the drawing surface by the specified amount.

Parameters

zoomPercentage	Percentage of drawing surface to zoom in by.
addToViewStack	Defaults true. Flag to indicate whether the new view

◆ zoomOut()

bool TSL3DInteractionModeManager::zoomOut	(	int	zoomPercentage,
		bool	addToViewStack = true )

Zoom out the drawing surface by the specified amount.

Parameters

zoomPercentage	Percentage of drawing surface to zoom out by.
addToViewStack	Defaults true. Flag to indicate whether the new view should be added to the view stack.

Returns: true if the zoom was successful and the view should be redrawn, false otherwise.

Member Data Documentation

◆ m_cameraManager

TSL3DInteractionCameraManager* TSL3DInteractionModeManager::m_cameraManager

protected

◆ m_display

TSL3DInteractionModeDisplay* TSL3DInteractionModeManager::m_display

protected

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ ~TSL3DInteractionModeManager()

◆ TSL3DInteractionModeManager()

Member Function Documentation

◆ addMode()

◆ getCameraPosition()

◆ getCurrentMode()

◆ onDraw()

◆ onLButtonDown()

◆ onLButtonUp()

◆ onMButtonDown()

◆ onMButtonUp()

◆ onMouseMove()

◆ onMouseWheel()

◆ onRButtonDown()

◆ onRButtonUp()

◆ onSize()

◆ queryCursor()

◆ queryPrompt()

◆ removeMode()

◆ resetMode()

◆ resetToDefaultView()

◆ resetToView()

◆ resetViews()

◆ savedViewGet()

◆ savedViewGoto()

◆ savedViewReset()

◆ savedViewSet()

◆ savedViewSetToCurrent()

◆ savedViewValid()

◆ setCameraPosition()

◆ setCurrentMode()

◆ setDefaultMode()

◆ setDefaultView()

◆ setElevation()

◆ setRotation()

◆ setViewedExtent()

◆ viewChanged()

◆ viewStackGetCurrent()

◆ viewStackGotoNext()

◆ viewStackGotoPrevious()

◆ viewStackNextValid()

◆ viewStackPreviousValid()

◆ viewStackReset()

◆ viewStackSize()

◆ zoomIn()

◆ zoomOut()

Member Data Documentation

◆ m_cameraManager

◆ m_display