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)

Activate a tool by its data-element.

/**
 * @method UI.setActiveTool
 * @param {string} dataElement The dataElement of the tool to activate.
 */
UI.setActiveTool('annotationHighlightButton');

Internally: if dataElement is falsy or disabled, calls useDocument.setToolState() (clears). Otherwise looks up map[dataElement] from constants/toolNames; if missing, warns and returns; else calls useDocument.setToolState(tool.toolName || tool.tool).

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 push directly through Core:
instance.Core.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