![]() |
MapLink Pro 11.1.1.0.
Envitia MapLink Pro: The Ultimate Mapping Application Toolkit
|
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 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 TSLInteractionModeManager derived classes, passing in a callback handler - derived from TSLInteractionModeRequest. 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 TSLInteractionModeManager and TSLInteractionModeDisplay. The TSLInteractionModeManager instance will create the appropriate version of the TSLInteractionModeDisplay class for internal use by the interaction modes.
The application should create instances of individual TSLInteractionMode 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.
Public Member Functions | |
virtual | ~TSLInteractionModeManager () |
bool | addMode (TSLInteractionMode *mode, bool isDefault) |
int | getCurrentMode (TSLInteractionMode **mode=0) const |
int | getMode (int nth, TSLInteractionMode **mode=0) const |
int | numModes () 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) |
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) |
void | onSize (TSLDeviceUnits cx, TSLDeviceUnits cy) |
TSLCursorStyle | queryCursor () |
const char * | queryPrompt () |
TSLInteractionMode * | removeMode (int id) |
void | resetMode (TSLButtonType button, TSLDeviceUnits x, TSLDeviceUnits y) |
bool | resetToExtent (const TSLEnvelope &extent, bool addToViewStack=true) |
bool | resetToFullExtent (bool addToViewStack=true) |
void | resetViews () |
bool | savedViewGet (int idx, TSLEnvelope &extent) |
bool | savedViewGoto (int idx) |
bool | savedViewReset () |
bool | savedViewSetToCurrent (int idx) |
bool | savedViewSet (int idx, const TSLEnvelope &extent) |
bool | savedViewValid (int idx) |
bool | setCurrentMode (int id) |
bool | setDefaultMode (int id) |
bool | setViewedExtent (const TSLEnvelope &extent, bool addToViewStack=true) |
void | viewChanged (bool addToViewStack) |
bool | viewStackGetCurrent (TSLEnvelope &extent) |
bool | viewStackGotoNext () |
bool | viewStackGotoPrevious () |
bool | viewStackNextValid () |
bool | viewStackPreviousValid () |
bool | viewStackReset () |
int | viewStackSize () |
bool | zoomIn (int zoomPercentage, bool addToViewStack=true) |
bool | zoomOut (int zoomPercentage, bool addToViewStack=true) |
Protected Member Functions | |
TSLInteractionModeManager (TSLInteractionModeRequest *requestHandler, int maxViewStackSize=5, int numSavedViews=5, int mouseWheelZoomPercentage=30, bool lockCursorOnMouseWheel=false) | |
Protected Attributes | |
void * | m_modes |
TSLInteractionMode * | m_currentMode |
TSLInteractionModeRequest * | m_requestHandler |
TSLInteractionMode * | m_defaultMode |
TSLInteractionModeDisplay * | m_display |
|
virtual |
The virtual destructor of the TSLInteractionModeManager. It destroys all memory allocated internally and also deletes the mode instance objects.
|
protected |
This is the constructor for the base TSLInteractionModeManager. It is an abstract base class and cannot be instantiated directly. The arguments to this are explained in the derived classes.
bool TSLInteractionModeManager::addMode | ( | TSLInteractionMode * | mode, |
bool | isDefault ) |
Adds a mode to the list managed by this TSLInteractionModeManager.
The TSLInteractionModeManager assumes ownership of the mode, which will be destroyed when the manager instance is deleted.
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. |
int TSLInteractionModeManager::getCurrentMode | ( | TSLInteractionMode ** | mode = 0 | ) | const |
Query the id and instance of the currently active mode.
Returns by value the id property of the currently active mode, 0 if no mode is currently active.
Returns by reference the mode instance.
int TSLInteractionModeManager::getMode | ( | int | nth, |
TSLInteractionMode ** | mode = 0 ) const |
Query the id and instance of the nth mode, when nth is a value between 0 and numModes() - 1.
Returns by value the id property of the nth mode, 0 on error.
Returns by reference the mode instance.
int TSLInteractionModeManager::numModes | ( | ) | const |
Returns the number of modes currently contained within the manager.
void TSLInteractionModeManager::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.
(x1,y1) | Bottom left, in device units, of the area being redrawn. |
(x2,y2) | Top right, in device units, of the area being redrawn. |
|
virtual |
Gesture handler for interaction modes. This event will be passed on to the currently active mode.
(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. |
|
virtual |
Gesture handler for interaction modes. This event will be passed on to the currently active mode.
(firstFingerX,firstFingerY) | Location of the press, in device unit coordinates. |
lDelta | Distance of the tap from the press, in device units |
|
virtual |
Gesture handler for interaction modes. This event will be passed on to the currently active mode.
(cx,cy) | Centre of the rotate gesture, in device unit coordinates. |
(dblAngle) | Angle to set the drawing surface rotation to. |
|
virtual |
Gesture handler for interaction modes. This event will be passed on to the currently active mode.
(x,y) | Location of the tap, in device unit coordinates. |
|
virtual |
Gesture handler for interaction modes. This event will be passed on to the currently active mode.
(cx,cy) | Location of the centre of the tap, in device unit coordinates. |
|
virtual |
Gesture handler for interaction modes. This event will be passed on to the currently active mode.
(cx,cy) | Position of centre of the zoom pinch event, in device unit coordinates. |
zoomFactor | Scaling factor to apply to current view |
|
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
(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. |
|
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
(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. |
|
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
(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. |
|
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
(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. |
|
virtual |
Mouse move handler for interaction modes. This event will be passed on to the currently active mode.
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. |
bool TSLInteractionModeManager::onMouseWheel | ( | short | delta, |
TSLDeviceUnits | x, | ||
TSLDeviceUnits | y ) |
Mouse wheel hander for interaction modes. This event will be passed on to the currently active mode.
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.
delta | Delta value of mouse wheel movement. See Windows help for further information. |
(x,y) | Position of locator event, in client window device unit coordinates |
|
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
(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. |
|
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
(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. |
void TSLInteractionModeManager::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.
cx | New width of drawing surface. |
cy | New height of drawing surface. |
TSLCursorStyle TSLInteractionModeManager::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.
const char * TSLInteractionModeManager::queryPrompt | ( | ) |
Query prompt to display for currently active mode.
TSLInteractionMode * TSLInteractionModeManager::removeMode | ( | int | id | ) |
This method removes the specified mode from the manager, returning ownership back to the application.
id | ID of mode to remove |
void TSLInteractionModeManager::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.
button | Button pressed which triggered deactivation (if any) |
(x,y) | If button pressed to trigger deactivation, location in device coordinates of press. |
bool TSLInteractionModeManager::resetToExtent | ( | const TSLEnvelope & | extent, |
bool | addToViewStack = true ) |
Request to set the view to a specified extent (in TMC units).
This may typically be used to define a start position from a previous session.
extent | Extent to reset to. |
addToViewStack | Defaults true. Flag to indicate whether this extent should be added to the view stack. |
bool TSLInteractionModeManager::resetToFullExtent | ( | bool | addToViewStack = true | ) |
Request to set the view to a display all data currently added to the drawing surface.
This calls the TSLDrawingSurface::reset method.
addToViewStack | Defaults true. Flag to indicate whether this extent should be added to the view stack. |
void TSLInteractionModeManager::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.
bool TSLInteractionModeManager::savedViewGet | ( | int | idx, |
TSLEnvelope & | extent ) |
Query the extent of a saved view.
If the view has not been saved, or an invalid index is passed, then this method returns false.
idx | Index of saved view to query. The index is zero-based. |
extent | [out] The specified saved view. |
bool TSLInteractionModeManager::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.
idx | Index of saved view to go toThe index is zero-based. |
bool TSLInteractionModeManager::savedViewReset | ( | ) |
Clears all saved views.
Returns true if successful, false otherwise. Failure typically occurs only if the saved view array was not initialised properly.
bool TSLInteractionModeManager::savedViewSet | ( | int | idx, |
const TSLEnvelope & | extent ) |
Set the specified saved view to be the specified extent.
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.
idx | Index of saved view to store into. The index is zero-based. |
extent | Extent to save. |
bool TSLInteractionModeManager::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.
idx | Index of saved view to store into. The index is zero-based. |
bool TSLInteractionModeManager::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.
idx | Index of saved view to query. The index is zero-based. |
bool TSLInteractionModeManager::setCurrentMode | ( | int | id | ) |
Sets the current mode to that specified.
If a different mode is active, then it is deactivated before the specified mode is activated.
id | Id property of the mode to activate. This is passed in the constructor of the mode and must be unique. |
bool TSLInteractionModeManager::setDefaultMode | ( | int | id | ) |
Allows the application to set the default mode.
id | ID of mode to set as the new default |
bool TSLInteractionModeManager::setViewedExtent | ( | const TSLEnvelope & | extent, |
bool | addToViewStack = true ) |
Request to set the view to a specified extent (in TMC units).
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 extent. This method is a synonym for resetToExtent.
extent | Extent to reset to. |
addToViewStack | Defaults true. Flag to indicate whether this extent should be added to the view stack. |
void TSLInteractionModeManager::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
addToViewStack | Flag to indicate whether the current view of the drawing surface should be added to the view stack. |
bool TSLInteractionModeManager::viewStackGetCurrent | ( | TSLEnvelope & | extent | ) |
Query for the current extent from the view stack. This is normally the same as the current view of the drawing surface.
extent | Storage to return the extent. |
bool TSLInteractionModeManager::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.
bool TSLInteractionModeManager::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.
bool TSLInteractionModeManager::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 viewStackGotoNext.
Returns false if the view stack cursor is at the end of the stack, true otherwise.
bool TSLInteractionModeManager::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 viewStackGotoPrevious.
Returns false if the view stack cursor is at the end of the stack, true otherwise.
bool TSLInteractionModeManager::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.
int TSLInteractionModeManager::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.
bool TSLInteractionModeManager::zoomIn | ( | int | zoomPercentage, |
bool | addToViewStack = true ) |
Zoom in the drawing surface by the specified amount.
zoomPercentage | Percentage of drawing surface to zoom in by. |
addToViewStack | Defaults true. Flag to indicate whether the new view should be added to the view stack. |
bool TSLInteractionModeManager::zoomOut | ( | int | zoomPercentage, |
bool | addToViewStack = true ) |
Zoom out the drawing surface by the specified amount.
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. |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |