Acetate Tools

The PureWeb SDK's acetate tools allow 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.

Overview

The SDK provides two tools by default, cursor and polyline. You can extend this functionality by creating your own markup tools.

  • 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.

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. 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.

Typically in the client's user interface, the Acetate feature will be provided as a checkbox that can easily be toggled on and off. In a collaboration session, when an end user selects the feature in his or her client application, this has the following effects:

  • automatically display the user's Acetate layer (cursor and/or markups) to all other participants
  • shows to the user the other participants' Acetate layer, but only for the participants who have enabled the Acetate in their own client

In other words, by enabling the Acetate, users automatically see all displayed markups, their own and the other participants', and by disabling the acetate, they automatically hide all markups. Note that disabling the acetate does not erase the markups, only hides them from view. The SDK provides other functions for clearing markups, such as ClearMarkupTool and removeAcetateMarkupByTools.

In the APIs, the classes required to implement Acetate are part of the client-side collaboration namespace.

Setting Up Acetate

There are four main steps to setting up an Acetate tool in a client application:

  • Create a function that adds the tool to the client when the user connects
  • Set up the tool's visibility so that it is hidden by default
  • Create an interface element that provides the user with a means to toggle the tool
  • Define the function that will display or hide the tool when the user interacts with the interface element

Adding the Tool Upon User Connect

The acetate tool will be added to the client once the client connects. The first step, therefore, is to listen for a connection state change event. The listener would normally be added to the method that launches the application. Below is an example in JavaScript:

pureweb.listen(pureweb.getClient(), pureweb.client.WebClient.EventType.CONNECTED_CHANGED, onConnectedChanged);

In the code above, the listener triggers a onConnectedChanged handler when the user connects. This is the function that will set up the acetate tool in the client. This involves:

  • adding a chosen tool type (CursorPositionTool or PolylineTool) to a toolset
  • associating the toolset with a particular view
  • activating the tool

Below is an example of what this code might look like in JavaScript. In this example, the view that the toolset is associated with is called scribbleView.

function onConnectedChanged(e) {

     var toolset = new pureweb.client.collaboration.AcetateToolset();
     var polylineToolDelegate = new pureweb.client.collaboration.PolylineTool();
     var polylineTool = toolset.registerToolDelegage(polylineToolDelegate);

     toolset.setDefaultTool(polylineTool);
     scribbleView.setAcetateToolset(toolset);

    toolset.activateTool(polylineTool);
}

Setting Up the Tool's Visibility

The tool's visibility is set using a boolean variable. This consists in two short lines of code:

First, add a top-level variable:

var acetateVisible;

Then, set this variable to false by default:

acetateVisible = false;

Create an Interface Element to Toggle the Acetate Tool

End users need an interface element such as a checkbox that allows them to turn the acetate tool on and off. You use your platform's native elements for this. Below is an example in HTML5. In this example, the client will run the onAcetateToggle function whenever the user clicks on the checkbox labeled Acetate:

<div style="float:right;">
    <input type="checkbox" onclick="onAcetateToggle();"> Acetate </input>
</div>

Define the Function Associated with the Interface Element

This function (labeled onAcetateToggle in the example above) changes the value of the previously created acetateVisible variable to true or false as required.

Also, because the acetate overlay is usually synchronized among several participants in a collaboration session, when the acetate layer is made visible, this must apply to a specific collaboration session only. This is achieved by setting the setMarkupVisible value to true or false for the session whose markup should be visible:

collaborationManager.setMarkupVisible(someSessionID, true)

Below is what this might look like for an HTML5 client.

function onAcetateToggle(e) {

    var collaborationManager = pureweb.getFramework().getCollaborationManager();
    var localSession = pureweb.getFramework().getClient().getSessionId();

    //If Acetate Not Currently Visible
    if(acetateVisible === false) {
        scribbleView.setInputTransmissionEnabled(false);

         acetateVisible = true
         collaborationManager.setMarkupVisible(localSession, true);
     }
     //If Acetate Already Visible
    else {
         scribbleView.setInputTransmissionEnabled(true);

        acetateVisible = false;
        collaborationManager.setMarkupVisible(localSession, false);
    }
}

Note that when the user toggles the acetate visibility off, this does not clear the markups, it only hides them from view. To clear the markups, you would follow a similar process by providing an interface element for this feature and using the one of the functions provided for clearing markups, including:

  • ClearMarkupTool
  • removeAcetateMarkupByTools
  • removeAcetateMarkupByInstance
  • removeAcetateMarkupByType
  • removeAcetateMarkupBySession
  • removeAllAcetateMarkupBySession