Mouse tools are named, customizable instances that can be used by any Viewer instance. Each mouse tool has a type, which determines how the tool behaves and the properties the tool has.

Mouse Tool Names

Mouse tools are given a name when a mouse tool is created. This name is used to get and set the mouse tool that is used by the Viewer:

// The name of a new mouse tool
var myMouseToolName = "MyLineTool";

// Create the new mouse tool
PCCViewer.MouseTools.createMouseTool(
    myMouseToolName,
    PCCViewer.MouseTool.Type.LineAnnotation);

// Set the current mouse tool of the ViewerControl by passing the name
viewerControl.setCurrentMouseTool(myMouseToolName);

The mouse tool name also specifies the new mouse tool in the MouseToolChanged event:

// The MouseToolChanged event triggers when the mouse tool changed.
// Use the ViewerControl#getCurrentMouseTool() method or event#mouseToolName property
// to get the new mouse tool name.
viewerControl.on("MouseToolChanged", function(ev) {
    viewerControl.getCurrentMouseTool() == ev.mouseToolName;  // true
});

Mouse Tool Objects

PCCViewer.MouseTool objects represent mouse tools, and the objects can be used to configure the mouse tools.

These objects are returned when creating a mouse tool with method PCCViewer.MouseTools.createMouseTool(...). The object can be retrieved at a later time using the method PCCViewer.MouseTools.getMouseTool():

// Get the MouseTool object for an existing tool
var myMouseTool = PCCViewer.MouseTools.getMouseTool(myMouseToolName);

The MouseTool object has getters for the tool name and type:

myMouseTool.getName(); // returns "MyLineTool"
myMouseTool.getType(); // returns "LineAnnotation"

Depending on the tool type, additional getters or setters may be available to configure the tool:

// All mouse tools that draw a mark (annotation and redaction) have a
// getter `getTemplateMark()`
if (myMouseTool.getType() === "LineAnnotation") {
    // The method gives access to a template mark that configures how the tool draw
    // the annotation or redaction.
    // In this example the mouse tool is configured to draw a red line.
    myMouseTool.getTemplateMark().setColor("#FF0000");
}

Mouse Tool Type

• The mouse tool type specifies the behavior of a mouse tool.
• The API has many different mouse tool types, all of which are specified in the enumeration PCCViewer.MouseTool.Type.
• The mouse tool type is specified when creating the mouse tool, and it cannot be changed.

Multiple Mouse Tools of one Type

Creating multiple mouse tools of one type is useful if several pre-defined behaviors are needed for one type of mouse tool. For example, this gives the ability to create two text highlighter tools, one that highlights red and the other that highlights green:

// Create the red highlighter
PCCViewer.MouseTools.createMouseTool(
    "RedHighlighter",
    PCCViewer.MouseTool.Type.HighlightAnnotation)
        .getTemplateMark()
            .setFillColor("#FF0000");

// Create the green highlighter
PCCViewer.MouseTools.createMouseTool(
    "GreenHighlighter",
    PCCViewer.MouseTool.Type.HighlightAnnotation)
        .getTemplateMark()
            .setFillColor("#00FF00");

Pre-defined Named Mouse Tools

The file viewercontrol.js creates several named mouse tools as listed in the table below. These named mouse tools are used by the Viewer out-of-the-box.