The Tool Framework tutorial
Introduction
This tutorial is supposed to make you familiar with the Tool Framework.
The framework was introduced to KiCad sometime ago to accompany the
Graphics Abstraction
Layer in order
to give means to modify a PCB design. For more details, there is a brief
description available
here. It is also
very* recommended to have a look at the short
specification -
it pictures the framework in a very clear way.
Source code of the Tool Framework that you may be interested in, is
available in the KiCad
repository.
There are also a few tools available as examples: the Selection
Tool
and the Move
Tool.
The Push and Shove
router
also bases on the same framework, but is a little bit harder to follow.
For the time being, the Tool Framework & the Graphics Abstraction Layer are available only for pcbnew, but in the future there are high chances that it will extend to other applications.
To demonstrate the way of creating new tools, I am going to guide you through the coding process of a simple distance measurement tool. It is expected that after following the tutorial, you will end up with a tool that may be activated from a context menu, waits for two mouse clicks and then displays the distance between them.
Tool template
Majority of tools start in the same way - you need to add some new files
and edit a few of existing ones. The common place for putting tool files
working with pcbnew is pcbnew/tools. Let's create there
distance_tool.cpp & distance_tool.h, containing nothing but the most
basic template.
See the files:
distance_tool.h TODO: link to repository
distance_tool.cpp TODO: link to repository
It contains only three functions:
- Constructor
- Init() called only once, when the Tool Framework starts
- Reset() called every time a tool is reactivated (every time user
invokes a tool, after the tool has finished its operation)
To make it build together with other tools, we need to add an entry to
pcbnew/CMakeFiles.txt. TODO: diff?
Unfortunately, even after building
KiCad, there is no
way to invoke the tool. That's why, we need to register our tool in the
TOOL_MANAGER
and then prepare TOOL_ACTIONs (or at least one for activation) and make
our tool handle them.
Registration
This part is fairly simple, all you need for registering a tool is an
entry in pcbnew/pcb_tools.cpp:
TODO: diff from the repo
After that, the TOOL_MANAGER is aware of existence of our tool and
initiates it, when everything is ready for the Tool Framework to step
in. It is also required to receive events, but the topic will be
expanded later in the
text.
TOOL_ACTIONs
TOOL_ACTIONs are special events meant to let the tools interact together or give an easy way to activate a tool (using a hotkey or context menu).