Tools

Tools handle mouse/touch interaction for creating and manipulating annotations, form fields, measurements, and content. This guide covers the tool system and the APIs for activating, inspecting, and registering tools.

Tool registry

Tools are identified by tool name strings and data-element strings (the toolbar button that activates them). Both are centralized in packages/webview/src/constants/toolNames.js:

• ToolNames — UPPER_SNAKE → camelCase map of every tool name (View, Annotation, Form, Measurement, Content editor, Signature, Security).
• DataElementToToolName — reverse map from DataElements.*_BUTTON to ToolNames.*.
• map — { [toolName]: { tool, toolName? } } lookup used by the document store's setToolState to translate a UI tool key into core.setTool(tool, toolName) arguments.
• register(tool) — adds a custom tool to map (extensibility hook used by registerTool).

UI APIs

UI.setActiveTool(dataElement, options?)

Activate a tool by its data-element.

UI.setActiveTool(dataElement, options);

Name	Required	Type	Description
dataElement	yes	string	The data-element of the tool to activate.
options	no	object	The tool activation options.
options.continueAdding	no	boolean	Whether to keep the signature-field creation tool active after a signature field is created. The default value is false.

For example, use the following code to activate the highlight tool:

UI.setActiveTool('annotationHighlightButton');

To create multiple signature fields without reactivating the tool after every field, set continueAdding to true:

UI.setActiveTool('signatureFields', {
  continueAdding: true
});

continueAdding currently applies only to the signatureFields tool. It does not enable continuous creation for textfield, checkbox, radiobutton, or other form tools. Existing one-argument calls remain unchanged.

UI.getActiveTool()

Get the currently active tool object.

/**
 * @method UI.getActiveTool
 */
const tool = UI.getActiveTool();

Returns the getActiveTool getter from the document store.

UI.getTool(tool)

Get a tool's configuration object by key.

/**
 * @method UI.getTool
 * @param {string} tool
 * @returns {object}
 */
const cfg = UI.getTool('highlight');   // => { color, ... }

Returns a shallow copy { ...store[tool] } of the document-store tool entry (which holds the tool's style preset: color, opacity, stroke, etc.).

UI.getToolColor(tool)

Get the color of a tool.

/**
 * @method UI.getToolColor
 * @param {string} tool
 * @returns {string} color
 */
UI.getToolColor('square');   // => '#FF0000'

Returns store[tool].color.

UI.registerTool(tool, options)

Register a custom annotation tool.

/**
 * @method UI.registerTool
 * @param {Object} tool Tool instance to register.
 * @param {Object} options Registration options.
 * @returns {boolean} Whether the tool was registered.
 */
const ok = UI.registerTool(myTool, { /* … */ });

Registers the tool name in the local register table (constants/toolNames) and delegates to core.registerTool(tool, options) (the core bridge). The bridge probes for documentViewer.toolRegistry.register, falling back to documentViewer.registerTool, and returns false if neither exists.

Tool style presets

Each tool has a style preset in the document store (packages/webview/src/stores/modules/document.js):

Tool	Default style
highlight	color: '#FFEC66'
underline / squiggly / strikeout	color: '#FF0000'
square / arc / polygon / polyline / circle / arrow / line	color, opacity: '0.8', stroke: '1pt'
ink	color, opacity, stroke: '2pt'
freetext	color: '#000000'
text	color: '#FF0000'
redaction	color: '#000000'
remove	color: '#FF0000'
Form fields (textfield/checkbox/radiobutton/listbox/combobox/pushbutton)	color, borderColor

setActiveToolColor(color) writes this[activeTool].color and pushes the change into the engine via core.setTool(activeTool). setToolState(tool) toggles the tool off if it is already active, otherwise calls core.setTool(mapTool.tool, mapTool.toolName).

Tool categories

Category	Tools
View	Pan, CropPage, SelectText
Annotation	Text, Ink, Eraser, Highlight, Underline, Strikeout, Squiggly, Circle, Arc, Square, Polygon, Cloudy, Polyline, Arrow, Line, Freetext, Callout, Stamp, Signature, Image, Link
Form	Textfield, Checkbox, Radiobutton, Listbox, Combobox, Pushbutton
Measurement	Line, Polyline, Curve, Arc, Circle, Rectangle, Polygon (measurement variants)
Content editor	AddText, AddImage
Signature	SignatureFields, AddDigitalSign, AddElectronicSign
Security	Redaction, Remove

Related engine bridge functions

The core bridge exposes (see Core Bridge): setTool, switchTool, setToolMode, getToolMode, getToolStyles, setToolStyles, registerTool, setDefaultSelect, setEraseMode, getEraseMode.

Examples

Activate the highlight tool and set its color

UI.setActiveTool('annotationHighlightButton');
// the document store now drives the engine; to change color use the style panel
// or set the tool directly through docViewer:
docViewer.setTool('Highlight', 'highlight');

Register a custom tool

UI.registerTool(
  { toolName: 'myTool', /* tool implementation */ },
  { buttonName: 'myToolButton', icon: 'MyIcon' }
);

Related

• Annotations — annotation types and CRUD.
• Forms — form-field tools.
• Core Bridge — setTool, registerTool.
• API Reference