Request

Response

    Autodesk.Viewing
    Version 8 preview
    This page documents a preview of the Viewer SDK v8. APIs and content can still change before the final release.

    ToolController

    Core interface to add and remove canvas interactions to the viewer.

    new ToolController(viewerImpl, viewerApi, autocam, utilities, defaultHandler)

    This class is created internally by the Viewer api and is available via the “toolController” property of the Viewer3D api object. Client implementations should not normally instantiate this class directly.

    Parameters

    viewerImpl*
    object
    The viewer implementation object.
    viewerApi*
    object
    The viewer api object.
    autocam*
    object
    The Autocam interface object.
    utilities*
    object
    The ViewingUtilities object.
    defaultHandler*
    object
    The default event handling tool.
    * Required

    Methods

    registerTool(tool, onStateChanged)

    This method registers an event handling tool with the controller. This makes the tool available for activation and deactivation. Tools are registered under one or more names which must be provided via their “getNames” method. The tools “getNames” method must return an array of one or more names. Typically a tool will only have one name but if it wishes to operate in different modes it can use different names to activate the modes. Registered tools have the properties named “utilities” and “controller” added to them which refer to the ViewingUtilities object and this controller respectively. Tools may not use the name “default” which is reserved.

    Parameters

    tool*
    object
    The tool to be registered.
    onStateChanged*
    function
    callback to be called when disabling the tool through the modality map
    * Required

    deregisterTool(tool)

    This method deregisters an event handling tool with the controller afterwhich it will no longer be available for activation and deactivation. All names that the tool is registered under will be deregistered. If any tool is active at the time of deregistration will first be deactivated and it’s “deactivate” method will be called.

    Parameters

    tool*
    object
    The tool to be deregistered.
    * Required

    getTool(name)

    This method returns the tool registered under the given name.

    Parameters

    name*
    string
    The tool name to look up.
    * Required

    Returns

    typedescription
    object The tool registered under the given name or undefined if not found.

    getActiveToolName()

    This method returns the name of the topmost tool on the tool stack. If no tools are active the name of the default tool is returned (which is “default”).

    Returns

    typedescription
    string The tool name to look up.

    getActiveTool()

    This method returns the name of the topmost tool on the tool stack. If no tools are active the name of the default tool is returned (which is “default”).

    Returns

    typedescription
    string The tool name to look up.

    getActiveTools()

    Return the current tool stack.

    Returns

    typedescription
    Array
    • list of tools in the tool stack

    rearrangeByPriorities()

    Sorts the toolStack according to the tools’ priority. Useful when a tool’s priority gets changed after activation.

    activateToolModality(toolName)

    Disables or enables tools in the tool’s modality map

    Parameters

    toolName*
    string
    Name of the tool
    * Required

    activateTool(toolName)

    Activates the tool registered under the given name. Activation implies pushing the tool on a stack of “active” tools, each of which (starting from the top of the stack) is given the opportunity to handle incoming events. Tools may “consume” events by returning true from their event handling methods, or they may allow events to be passed down to the next tool on the stack by returning false from the handling methods. Upon activation the tools “activate” method is called with the name under which it has been activated. Activation is not allowed while the controller is in a “locked” state (see the methods “setIsLocked” and “getIsLocked”). Tools must be registered prior to activation (see the methods “registerTool” and “deregisterTool”). Each tool has its own priority property (default 0), such that a tool with higher priority will get events first.

    Parameters

    toolName*
    string
    The name of the tool to be activated.
    * Required

    Returns

    typedescription
    boolean True if activation was successful.

    deactivateTool(toolName)

    The first tool found on the active stack with the given name is removed and its “deactivate” method is called. Once deactivated the tool will no longer receive events via its handler methods. Deactivation is not allowed while the controller is in a “locked” state (see the methods “setIsLocked” and “getIsLocked”).

    Parameters

    toolName*
    string
    The name of the tool to be deactivated.
    * Required

    Returns

    typedescription
    boolean True if deactivation was successful.

    getToolNames()

    Obtain a list of all the currently registered tool names.

    Returns

    typedescription
    Array List of all registered tool names.

    setDefaultTool(tool)

    Set the tool which will be requested to handle events if no other active tool handles them.

    Parameters

    tool*
    object
    The tool to be registered as the default.
    * Required

    getDefaultTool()

    Get the tool which handle events if no other active tool handles them.

    Returns

    typedescription
    object The tool to be registered as the default.

    setIsLocked(state)

    Set the controller into a locked or unlocked state. While locked, tool activation and deactivation is not allowed. Locking the controller is sometimes necessary to force an interaction to remain active until it is fully completed.

    Parameters

    state*
    boolean
    The state of the controller lock.
    * Required

    Returns

    typedescription
    boolean The previous state of the lock (this may be used to restore the lock to it’s previous state).

    getIsLocked()

    Get the current state of the controller lock.

    Returns

    typedescription
    boolean The state of the lock.

    handleCmdKeyEvent(cmdEvent, eventType)

    Catches a CMD event and generates a control event instead.

    Parameters

    cmdEvent*
    object
    Event generated by CMD key
    eventType*
    string
    Event type
    * Required

    setMouseWheelInputEnabled(isEnabled)

    Whether mouse scroll wheel (and/or two-finger vertical swipe) will trigger a camera zoom operation.

    Parameters

    isEnabled*
    boolean
    * Required

    setModalityMap(map)

    Set the modality map for each tool. This function will clear any existing modality map. The map object consists of a key which represents the tool name and a value which is an object that represents which tools to enable and disable. To get the tool names @see ToolController#getToolNames

    Parameters

    map*
    object
    Object describing each tool’s modality with other tools.
    * Required

    Examples

    // When enabling the measure tool the explode, bimwalk and section tools will be disabled.
    // When enabling the section tool the pan tool will be disabled.
    toolController.setModalityMap({
        measure: { explode: false, bimwalk: false, section: false },
        section: { pan: false }
    });
    

    getModalityMap()

    Get the modality map.

    Returns

    typedescription
    object
    • returns a copy of the tool modality.

    getToolModality(name)

    Get a specific tool’s modality map.

    Parameters

    name*
    string
    tool name
    * Required

    Returns

    typedescription
    object
    • an object describing the tool’s modality map.

    setToolModality(name, map)

    Parameters

    name*
    string
    Tool name that is associated with the modality map.
    map*
    object
    Object containing the name of the tool as the key and a boolean that describes if the tool can be enabled or disabled.
    * Required