StandardTool Class
An advanced tool for interacting with 2D maps.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class StandardTool : ToolRemarks
StandardTool is a general-purpose tool implementation, providing a range of different functions for a user to interact with a 2D map. It supports different methods of panning and zooming, selecting objects in the map, moving complete objects or parts of objects, and even adding and removing nodes of existing features. Depending on how the user uses the mouse and keyboard, different interaction methods are invoked.
If your map is slow while panning or zooming and you have optimized the configuration as well as you can, you can still improve the visual feedback by using a temporary bitmap. Changing the UpdateMode to Bitmap, the tool takes a bitmap copy of the window contents when starting a pan or zoom. This bitmap is then used during the operation, instead of calling View.Update repeatedly. When zooming in, the image will be more blurry. Zooming out will show the Drawable.Background in places where the map has not been rendered yet. The operation is always finished with a complete update, to restore full image quality and render the parts of the map that are not yet rendered. If your slow layers are using a TileLayer this function is not needed. The function is more used if you have a lot of slow vector layers that need to be shown. If it is acceptable to hide some of the vector layers while panning or zooming, this can be done to improve the performance while still seeing the background map being updated by the TileLayer. See QuickUpdateEnabled for more information.
The application can set other properties on the tool, to turn other functions on or off, or to control at which speed certain operations occur. The tool may temporarily add visual cues to the display. These can also be controlled by properties.
Supported Interactions
The tool has several functions and the way you switch between these depend on what interaction and navigation mode is set. In the default mode, mouse buttons and the keyboard are used to switch between modes. Most of the functions can also be enabled or disabled using bool properties. It is also possible to switch to some of the modes manually by using the InteractionMode and NavigationMode properties.
The editing operations only work if the feature is in a layer that is selectable (Layer.selectable), the layer's parent layers are selectable and the feature is stored in a dataset that is writable (i.e. it has to be a MemoryDataSet).
The StandardTool does not let you create new features; use CreateTool for that.
Navigation
Interaction | Behavior |
|---|---|
Left-button on background and dragging | Pans the map |
Left-button double click | Zooms in a set amount. Keeps the clicked location in the same place on the screen |
Right-button and dragging | Zooms in an amount based on how much the mouse is moved. Keeps the clicked location in the same place on the screen |
Use scroll wheel | Zooming (continuous). Keeps the clicked location in the same place on the screen |
Pressing Shift and right-button and dragging | Creates a rectangle on the map and zooms to it |
General Editing
Interaction | Behavior |
|---|---|
Let cursor hover over selectable feature | Replaces the default Cursor by the SelectFeature cursor (hover visualizers are applied) |
Left-button click on selectable feature | Selects the feature (selection visualizers are applied). |
Pressing Shift and left-button and dragging | Creates a rectangle and selects the features in it |
Left-button on a selectable feature and dragging | Moves the feature |
Left-button click once on linepolygon node and dragging | Moves the node. This operation requires a selection visualizer for the nodes. |
Pressing Alt and left-button click on a node in the selected linepolygon | The node is removed. This operation requires selection visualizers. One for the nodes and a LineVisualizer for the linepolygon |
Pressing Alt and left-button click on an edge of the selected linepolygon | A new node is added. This operation requires selection visualizers. One for the nodes and a LineVisualizer for the linepolygon |
Ellipse Editing
Ellipse interaction symbols are generated by the InteractionVisualizer. You can find information on setting up the interaction in Interacting with Ellipses.
Interaction | Behavior |
|---|---|
Left-button on center symbol and dragging | Moves the center |
Left-button on circle radius symbol and dragging | Changes the radius and direction |
Left-button on circle inner radius symbol and dragging | Changes the inner radius and direction |
Interaction | Behavior |
|---|---|
Left-button on center symbol and dragging | Moves the center |
Left-button on ellipse primary radius symbol and dragging | Changes the radius and the direction. The ratio is also changed so that the ellipse is only changed in one direction |
Left-button on ellipse secondary radius symbol and dragging | Changes the ratio |
Interaction | Behavior |
|---|---|
Left-button on center symbol and dragging | Moves the center |
Left-button on middle symbol and dragging | Changes the radius and the start and end angle of the sector so that the middle of the sector is where the cursor is |
Left-button on left symbol and dragging | Depending on the EllipseOperator.SectorDefinition, changes the radius and/or start angle and/or width of the sector |
Left-button on right symbol and dragging | Depending on the EllipseOperator.SectorDefinition, changes the inner radius and/or finish angle and/or width of the sector |
On Linux, many window managers will take care of mouse events if the Alt key is pressed. This will disable node add and removal. A workaround for this problem is to hold down Shift or Ctrl before pressing Alt as you left-button click to add or remove a node on a selected entity.
StandardTool is not supported on Android.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Tool
StandardTool
Platforms
Windows, Linux, Android
StandardTool Members
The StandardTool type has the following members.
Constructors
| Name | Description |
|---|---|
| StandardTool | Initializes a new instance of the StandardTool class. |
Properties
| Name | Description |
|---|---|
| CompassPoleLongLat | Gets or sets an anchor point used when objects are moved on earth, controlling the rotation of the objects. |
| EditEnabled | Gets or sets a flag indicating if the user can edit features with the mouse. |
| FillColor | Gets or sets the color used for filling the selection rectangle. |
| HotTrackingEnabled | Gets or sets a value controlling if the mouse cursor is changed when moving over a selectable feature. |
| InteractionMode | Gets or sets the tool interaction mode. Use this to override the default tool interaction. |
| IsDisposed | Gets a value that tells whether the current StandardTool has been disposed. Inherited from EngineObject |
| KineticScrollingEnabled | Gets or sets a flag indicating if kinetic scrolling is enabled. |
| MaximumEllipseRatio | Gets or sets a value indicating the maximum allowed EllipseOperator.Ratio when editing ellipses. The most useful case is when you want the axis that is along the EllipseOperator.Direction to always be longer than the axis that is defined by the EllipseOperator.Direction. You can then set the value of this property to 1.0. A value of 0.0 means that there is no maximum ratio. |
| MouseDoubleClickZoomEnabled | Gets or sets a flag indicating if the user may zoom the view by double-clicking the left mouse button. |
| MouseHysteresis | Gets or sets the maximum distance the mouse can be moved until a pan or move operation is started instead of a selection. |
| MousePanEnabled | Gets or sets a flag indicating if the user may pan the view by dragging the mouse while holding the left mouse button. |
| MouseWheelZoomEnabled | Gets or sets a flag indicating if the user may zoom the view with the mouse wheel. |
| MouseWheelZoomSpeed | Gets or sets a value controlling the amount the view is zoomed in response to mouse wheel events. |
| MouseZoomEnabled | Gets or sets a flag indicating if the user may zoom the view by dragging the mouse while holding the right mouse button. |
| MouseZoomSpeed | Gets or sets a value controlling the amount the view is zoomed in response to mouse move events. |
| MoveMode | Gets or sets a value controlling how features are moved. |
| MultiSelectEnabled | Gets or sets a flag indicating if selecting multiple features using the mouse and control key is enabled. |
| NativeHandle | Gets the native Carmenta Engine kernel object the current StandardTool represents. Inherited from EngineObject |
| NavigationMode | Gets or sets the navigation mode. Use this to override the default tool navigation. |
| OutlineColor | Gets or sets the color used for outlining the selection rectangle. |
| PointerRadius | Gets or sets the pointer radius for hit-testing. |
| QuickUpdateEnabled | Gets or sets a flag indicating if certain layers should be turned off during mouse interactions. |
| RectangleSelectEnabled | Gets or sets a flag indicating if the user may select features inside a rectangle using the left mouse button and shift key is enabled. |
| RectangleZoomEnabled | Gets or sets a flag indicating if the user may zoom via a rectangle using the right mouse button and shift key is enabled. |
| SelectEnabled | Gets or sets a flag indicating if selecting features with the mouse is enabled. |
| UpdateMode | Gets or sets a value controlling how the view is updated during a pan or zoom operation. |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| ITool.IsActive | Indicates if the tool is active with a user interaction. Inherited from ITool |
| ITool.OnConnect | Called when a tool is connected to the map control. Inherited from ITool |
| ITool.OnDisconnect | Called when the tool is disconnected from the map control. Inherited from ITool |
| ITool.OnKeyDown | Called when a key is pressed. Inherited from ITool |
| ITool.OnKeyUp | Called when a key is released. Inherited from ITool |
| ITool.OnMouseDoubleClick | Called when a mouse button is double clicked. Inherited from ITool |
| ITool.OnMouseDown | Called when a mouse button is pressed. Inherited from ITool |
| ITool.OnMouseMove | Called when the mouse is moved. Inherited from ITool |
| ITool.OnMouseUp | Called when a mouse button is released. Inherited from ITool |
| ITool.OnMouseWheel | Called when the mouse wheel is moved. Inherited from ITool |
Events
| Name | Description |
|---|---|
| Interacted | Occurs when a user completes (or aborts) an interaction. |
| Interacting | Occurs when a user interacts with features in a selectable layer. |
| Selecting | Occurs when a user has clicked one ore more features and the tool is about to add them to the selection of the view. Please note that the layer must be selectable. |