This page focuses on the role of the
ToolController object, that allows to manage multiple tools in iink SDK.
The iink v1.x API used to consider that pen events were dedicated to write or edit content (text, math or shape content, edit gestures, etc.) and touch events to manipulate content (select, drag & drop, scroll, etc.).
The introduction of the
ToolController object enables to associate input sources with interaction tools, such as pen, eraser, highlighter and selector. For instance, a pen input can now be used to select content with the selector (lasso) tool.
To do so, the
ToolController links pointer types representing input mediums to intents, so that you can customize their interaction patterns.
The point of contact can be made on the screen by several input devices.
PointerType enum defines this source of input. The possible values are:
PEN: an active stylus.
TOUCH: a finger on a touchscreen (or a passive stylus).
ERASER: an eraser or inverted pen.
MOUSE: a mouse.
In addition, we have planned some extra sources of input, in order to ease your integration of specific use cases or any new future pointer type. An example of usage would be a pen while holding a button.
The available enum values for such specific cases are:
The intent of the event on the content is defined by the
PointerTool enum. The possible values are:
PEN: corresponds to actions like writing or drawing some contents, performing ink gesture such as a scratch, or resizing a box by dragging its handle.
HAND: aims at interacting with already selected content, for instance for moving or resizing it, converting it.
ERASER: aims at erasing some content.
SELECTOR: aims at selecting some content by surrounding it with a lasso, so that further actions can be applied on the selection.
HIGHLIGHTER: aims at highlighting some content anywhere in a page, regardless of the type of paragraph or block or the presence of bold. It can also be used to color shapes or change text or ink color.
Mapping pointer types to tools is necessary so that iink knows how it should interpret the captured events.
For instance, it determines a selection by analysing the items within the lasso strokes when the
PEN pointer type is linked to the
SELECTOR pointer tool,
whereas it performs text and gestures recognition when the
PEN pointer type is linked to the
Engine object lets you create the
ToolController toolController = engine.createToolController();
By default, this
ToolController comes with a predefined cabling between pointer types and intents:
But should you want to use your input for another intent, you can customize your tool controller. All you have to do is modify the link between the input medium and the given intent.
For this purpose, you should call the
setToolForType method. For instance, if you want to use your active pen to highlight:
If you want to add a toolbar in your application, the
setToolForType method should be used when the user switches a tool mapped to the same input type: for instance from
You can draw on the
Demo example that implements a toolbar and illustrates how to switch tool.
In addition, this sample lets you choose whether you use an active pen mode or not: this mode relies on the principle of using the pen to write and the finger to manipulate content.
The following tables sums up the mapping choices of our
Demo example, that can guide you in your integration:
|Pointer Type||Pointer Tool in active pen mode||Pointer Tool with active pen disabled|
|PEN||Current selected tool1||Current selected tool2|
||Current selected tool2|
|MOUSE||Current selected tool1||Current selected tool2|
You can associate a style to a given tool.
setToolStyle method allows you to modify the predefined style coupled with tools that add content to the Content Part, like the
This method is useful when you want to let end users choose styling parameters like the color. For instance, they may want to write in blue and highlight in yellow.
For further guidelines on how to set a style, jump to the styling page.