Objects in the Visio Services JavaScript API

  • Article

Applies to: SharePoint Server 2010

In this article
VwaControl Object
Page Object
ShapeCollection Object
Shape Object

Note

The information in this topic applies to SharePoint 2013 as well as to SharePoint 2010.

The Visio ServicesJavaScript API contains only four objects and their respective members:

In addition, the Visio ServicesJavaScript API contains four enumerations:

VwaControl Object

The VwaControl object represents an instance of the Visio Web Access Web Part. By using the methods of the VwaControl object, you can access information about the Web Part and about the Visio drawing rendered in the Web Part. In addition, by using these methods, you can perform various actions, such as opening a Visio document in the Web Part, getting and setting the active page being displayed, adding or deleting event handlers, and displaying or hiding custom messages.

In your JavaScript code, you can get a reference to the VwaControl object by attaching a handler to the load event of the ASP.NET AJAXSys.Application class. In the function that implements that handler, you can initialize the object by passing it the HTML identifier (ID) of the Visio Web Access Web Part that you want to host the object. You can obtain that ID by examining the source code of the HTML page that hosts the Web Part, and searching for the phrase class="VisioWebAccess". The ID is in the format "WebPartWPQ#", where # represents the identifying number of the Web Part. The following code example shows how to do this. It assumes that you have determined that the Web Part ID is WebPartWPQ3, and that you have opened a Visio drawing that is published as a .vdw file in the Web Part. This is shown in the following code.

Sys.Application.add_load(onApplicationLoad)

var webPartElementID = "WebPartWPQ3";
var vwaControl;

function onApplicationLoad() {
        try{
                vwaControl= new Vwa.VwaControl(webPartElementID)
                vwaControl.addHandler("diagramcomplete", onDiagramComplete);
        }
        catch(err){
        }
}

When you get a reference to an instance of the VwaControl object, you can use its openDiagram method to open a new diagram, based on a published Visio .vdw file, in the Visio Web Access Web Part. However, after you call the openDiagram method, you cannot then address the same instance of the VwaControl or any other object in the Vwa namespace. That is because the openDiagram method is an asynchronous operation, which opens the diagram on the server and then returns immediately. In addition, the asynchronous operation also makes the current VwaControl object invalid. For information, see Vwa.VwaControl.openDiagram Method.

The best way to follow up on a call to openDiagram is to create a handler for the Vwa.diagramcomplete Event, which occurs when the Visio Web Access Web Part has finished loading the Visio diagram, and to put your code in that event handler. You can use the Vwa.VwaControl.addHandler Method to add an event handler for the diagramcomplete event. Best practice is to program the VwaControl object by writing these event handlers to respond to events raised by user actions in the control. Other events exposed by the VwaControl object include Vwa.shapemouseenter Event, Vwa.shapemouseleave Event, and Vwa.shapeselectionchanged Event, which enable you to respond to user mouse actions; and the Vwa.diagramerror Event, which enables you to respond to errors that SharePoint Server 2010 returns.

In the handler for the diagramcomplete event, you can get references to the other objects exposed by the API, including the Page object and Shape object, and the ShapeCollection collection. In the same handler, you can also create handlers for other events, as shown in the following code example.

function onDiagramComplete() {
        try {
                vwaPage = vwaControl.getActivePage();
                vwaShapes = vwaPage.getShapes();
                vwaShape = vwaShapes.getItemAtIndex(0);
                vwaControl.addHandler("shapeselectionchanged", onShapeSelectionChanged);
        }
        catch(err) {
        }
}

This code example shows how to complete the following programming tasks:

  • How to use the Vwa.VwaControl.getActivePage Method to get a reference to an instance of the Page object that represents the active page

  • How to use the Vwa.Page.getShapes Method of the Page object to get an instance of the ShapeCollection collection that represents the collection of shapes on the active page

  • How to use the Vwa.ShapeCollection.getItemAtIndex Method of that collection to get an instance of the first shape in the collection of shapes on the active page

  • How to add a handler for the shapeselectionchanged event

To get more information about the drawing that is displayed in the Web Part, you can use several methods of the VwaControl object. For example, you can use the Vwa.VwaControl.getAllPageIds Method to get the names of all the pages contained in the diagram. You can use the Vwa.VwaControl.getDiagramUrl Method to get the URL of the diagram that is currently displayed in the Web Part, and the Vwa.VwaControl.getDisplayMode Method to determine whether the current Web drawing page is displayed by using raster technology or Microsoft Silverlight technology. You can also use the Vwa.VwaControl.getVersion Method to get the version of the Web Part.

The Vwa.VwaControl.removeHandler Method lets you remove an event handler you added, and the Vwa.VwaControl.clearHandlers Method removes all handlers. To display and hide custom HTML error message pages, use the Vwa.VwaControl.displayCustomMessage Method and Vwa.VwaControl.hideCustomMessage Method. You can also use the Vwa.VwaControl.setActivePage Method to change the page that is currently displayed in the Web Part, and the Vwa.VwaControl.refreshDiagram Method to refresh the current Web drawing page by using data from the server.

Page Object

The Page object represents the active Web drawing page that is currently displayed in the rendering area of the Visio Web Access Web Part. You can use the methods of the Page object to select shapes on the page and to access information about shapes, including the ID of a shape, the position of the shape, and the size of the bounding box around the shape. You can also get and set the zoom level and the position of the page in the view.

Methods of the Page object include the following:

ShapeCollection Object

The ShapeCollection object represents the collection of shape objects on the active page in the Web drawing that is currently displayed in the rendering area of the Visio Web Access Web Part.

Methods of the ShapeCollection object include the following:

Shape Object

The Shape object represents a single shape on the active Web drawing page. Methods of the Shape object enable you get information about and interact with a specific shape on the active page: