pureweb.client.collaboration. AcetateToolDelegate

Defines the interface supported by all acetate drawing tool instances. This interface must be implemented by all acetate tools.

About Acetate Tools

PureWeb's acetate functionality allows you to display an overlay over views for markup purposes; this can enhance the collaboration experience by allowing each participant to see what the other participants are doing. The API provides two tools by default, cursor (CursorPositionTool) and polyline (PolylineTool). The cursor tool displays an arrow indicating where a user's mouse is pointing. The polyline tool displays a user's free-form drawings over a view (if the user is collaborating from a desktop device).

By default, acetate tools are not mutually exclusive: you can display cursors and polyline drawings (or any other markups from custom tools) simultaneously in the same view, although this is customizable by setting the isMutuallyExclusive property. The AcetateToolset class is responsible for managing which tools are active in a view at any given time and for broadcasting to the view the event raised in the acetate.

To clear markups once they are no longer needed, you would use the methods provided in ClearMarkupTool.

Method Summary

getMarkupType
Returns the markup type.
isMutuallyExclusive
Returns a Boolean value that indicates whether this tool is mutually exclusive with others.
isOneShot
Returns a Boolean value that indicates whether this instance is a one-shot tool.
onActivated
Activates the tool for the specified view.
onCancelMode
Cancels any mode the tool is in, and ends its current markup.
onDeactivated
Deactivates the tool for the specified view.
onDraw
Draws any data specified in markup.
onViewKeyboardEvent
Called when the view queues a keyboard event and the CollaborationManager instance is initialized.
onViewMouseEvent
Called when the view queues a mouse event and the CollaborationManager instance is initialized.

Method Detail

getMarkupType() → {string}

Returns the markup type. This must be unique for each type of tool, and identifies the schema of the draw data consumed and generated by this tool.

isMutuallyExclusive() → {boolean}

Returns a Boolean value that indicates whether this tool is mutually exclusive with others. Will return true if it is, or false otherwise.

This method is mandatory. AcetateTool will throw an exception on creation if this method is missing.

isOneShot() → {boolean}

Returns a Boolean value that indicates whether this instance is a one-shot tool. Will return true if it is, or false otherwise. A one-shot tool does not stay activated; it is immediately deactivated after activation.

This method is mandatory. AcetateTool will throw an exception on creation if this method is missing.

onActivated(tool)

Activates the tool for the specified view. The tool should connect to any view events and other information sources.

This method is optional and will be ignored if not implemented.
Parameters:
Name Type Description
tool pureweb.client.collaboration.AcetateTool The tool that is being activated.

onCancelMode(tool)

Cancels any mode the tool is in, and ends its current markup.

This method is optional and will be ignored if not implemented.
Parameters:
Name Type Description
tool pureweb.client.collaboration.AcetateTool The tool that is cancelling.

onDeactivated(tool)

Deactivates the tool for the specified view. The tool should disconnect from any view events and other information sources.

This method is optional and will be ignored if not implemented.
Parameters:
Name Type Description
tool pureweb.client.collaboration.AcetateTool The tool that is being deactivated.

onDraw(tool, layer, sessionId, instanceId, markup, defaultColor)

Draws any data specified in markup. The surface Canvas will not retain any children between draw invocations. To avoid creating new draw objects on each call, you may consider using a ToolDrawObjectCache, which can store drawing objects based on session ID, view name, and an arbitrary object name.

The drawing operation is carried out independently of any view that the tool is currently activated for, so the tool should not base drawing on the current activation context.

This method is optional and will be ignored if not implemented.
Parameters:
Name Type Description
tool pureweb.client.collaboration.AcetateTool The tool that is drawing.
layer pureweb.client.collaboration.CollaborationLayer The layer.
sessionId string The session's unique identifier.
instanceId string The instance's unique identifier.
markup Element The markup.
defaultColor pureweb.PureWebColor The default color.

onViewKeyboardEvent(tool, event)

Called when the view queues a keyboard event and the CollaborationManager instance is initialized.

This method is optional and will be ignored if not implemented.
Parameters:
Name Type Description
tool pureweb.client.collaboration.AcetateTool The activated acetate tool.
event Object The details of the mouse event.

onViewMouseEvent(tool, event)

Called when the view queues a mouse event and the CollaborationManager instance is initialized. The mouse coordinates are in image coordinate space, not view coordinate space.

This method is optional and will be ignored if not implemented.
Parameters:
Name Type Description
tool pureweb.client.collaboration.AcetateTool The activated acetate tool.
event Object The details of the mouse event.