Tools Customization

RadDiagram provides a list of all available tools, which you can easily change to better fit your applicaiton logic. You can remove built-in tools, create custom ones and add them to the list or replace existing ones with them.

In RadDiagram the ToolService keeps a collection of tools in its ToolList property. This property is essentially a collection of objects implementing the ITool interface.

You can get the ToolService currently used by a RadDiagram instance through the ServiceLocator.GetService() method. You can read more about the ServiceLocator in the Services tutorial.

By default there are 14 tools registered in the following order in the ToolService ToolList collection:

• PointerTool - This is the default active tool in a diagram. It allows you to drag, select, resize items and etc.

• PathTool - A tool that allows you to draw polyline shapes.

• PencilTool - A tool that allows you to perform free hand drawing.

• TextTool - A tool that allows you to position and add text to your diagram.

• PanningTool - A tool that allows you to perform panning.

• ConnectionTool - A tool that allows to create connections. You can activate it by setting the RadDiagram.ActiveTool to ConnectorTool.

• DraggingTool - A tool that handles the translation of items on the diagramming surface, such as dragging shapes across the diagram.

• ConnectionManipulationTool - A tool that handles the changes of a connection, such as translating the intermediate connection points, adding and removing intermediate connection points or connecting or detaching endpoints to/from a shape's connector.

• ResizingToolNESW - A tool that handles the item's resizing from NorthEast to SouthWest.

• ResizingToolNWSE - A tool that handles the item's resizing from NorthWest to SouthEast.

• ResizingToolSENW - A tool that handles the item's resizing from SouthEast to NorthWest.

• ResizingToolSWNE - A tool that handles the item's resizing from SouthWest to NorthEast.

• RotationTool - A tool that handles the items' rotation.

• RectangleSelectionTool - A tool that allows you to draw a selection rectangle thus selecting all items within its bounds.

In order to access the ToolList collection, the object returned by the ServiceLocator.GetService() method should be cast to ToolService.

You can easily add, remove or replace tools from the above collection. It is also important to note that all these tools handle user interactions - mouse and keyboard actions, originating from the RadDiagram. This is why they have to handle mouse and keyboard events. In order to do so the services implement one or both of the following interfaces:

• IMouseListener - this interface describes the four fundamental methods of a mouse handler object - MouseDown, MouseDoubleClick, MouseMove and MouseUp. You can examine its members in the API reference

• IKeyboardListener - this interface describes the two fundamental methods of a keyboard handler object - KeyUp and KeyDown. You can examine its members in the API reference

The order of the tools added to the ToolList collection is important due to the fact that they all listen to the same mouse and keyboard events. As soon as an active tool detects a user interaction that it has to respond to, it notifies the ToolService not to propagate this event any further. This is why the tools next in line in the ToolList will not receive the inetraciton. This ensures that there is only one active tool at all times.

Getting a Tool

A tool can be get from the Tools collection of the diagram's ToolService.

Example 1: Getting a tool by name

ToolService toolService = xDiagram.ServiceLocator.GetService<IToolService>() as ToolService; 
PencilTool pencilTool  = (PencilTool)toolService.FindTool(PencilTool.ToolName); 

Dim toolService As ToolService = TryCast(xDiagram.ServiceLocator.GetService(Of IToolService)(), ToolService) 
Dim pencilTool As PencilTool = CType(toolService.FindTool(PencilTool.ToolName), PencilTool) 

Example 2: Getting a tool by index

ToolService toolService = xDiagram.ServiceLocator.GetService<IToolService>() as ToolService; 
PencilTool pencilTool = (PencilTool)toolService.ToolList[2]; 

Dim toolService As ToolService = TryCast(xDiagram.ServiceLocator.GetService(Of IToolService)(), ToolService) 
Dim pencilTool As PencilTool = CType(toolService.ToolList(2), PencilTool) 

Registering a Tool

To register or replace a tool you can use the Tools collection of the diagram's ToolService.

Example 3: Replace an existing tool

ToolService toolService = xDiagram.ServiceLocator.GetService<IToolService>() as ToolService; 
toolService.ToolList[2] = new MyPencilTool("MyPencilTool");  

Dim toolService As ToolService = TryCast(xDiagram.ServiceLocator.GetService(Of IToolService)(), ToolService) 
toolService.ToolList(2) = New MyPencilTool("MyPencilTool") 

Example 4: Register a new tool

ToolService toolService = xDiagram.ServiceLocator.GetService<IToolService>() as ToolService; 
MyCustomTool myCustomTool = new MyCustomTool("MyCustomTool"); 
toolService.ToolList.Add(myCustomTool); 

Dim toolService As ToolService = TryCast(xDiagram.ServiceLocator.GetService(Of IToolService)(), ToolService) 
Dim myCustomTool As MyCustomTool = New MyCustomTool("MyCustomTool") 
toolService.ToolList.Add(myCustomTool) 

Creating a Custom Tool

In order to create a custom tool, you can create a new class using one of the following approaches:

• Create a class that derives from one of the built-in tools described above.

• Create a class that derives from the ToolBase class and implements the IMouseListener and/or IKeyboardListener interfaces.

• Create a class that implements the ITool interface and one or both of the IMouseListener and IKeyboardListener interfaces.

See the CustomTools SDK example which demonstrates how to implement a custom tool. See also, the Customize the Path and Pencil Tools article.