Export (0) Print
Expand All

ProjectDocument.addHandlerAsync method (JavaScript API for Office)

apps for Office

Asynchronously adds an event handler for a change event in a ProjectDocument object.

Last modified: March 03, 2015

Hosts:

Project

Available in Requirement set

Selection

Added in

1.0

See all support details

Office.context.document.addHandlerAsync(eventType, handler[, options][, callback]);

Name

Type

Description

Support notes

eventType

EventType

The type of event to add, as an EventType constant or its corresponding text value. Required.

The following table shows valid eventType arguments for a ProjectDocument object.

Enumeration

Text value

Office.EventType.ResourceSelectionChanged

resourceSelectionChanged

Office.EventType.TaskSelectionChanged

taskSelectionChanged

Office.EventType.ViewSelectionChanged

viewSelectionChanged

handler

function

The name of the event handler. Required.

options

object

Specifies any of the following optional parameters

asyncContext

array, boolean, null, number, object, string, or undefined

A user-defined item of any type that is returned in the AsyncResult object without being altered.

callback

object

A function that is invoked when the callback returns, whose only parameter is of type AsyncResult.

When the callback function executes, it receives an AsyncResult object that you can access from the parameter in the callback function.

For the addHandlerAsync method, the returned AsyncResult object contains the following properties:

Name

Description

asyncContext

The data passed in the optional asyncContext parameter, if the parameter was used.

error

Information about the error, if the status property equals failed.

status

The succeeded or failed status of the asynchronous call.

value

addHandlerAsync always returns undefined.

The following code example uses addHandlerAsync to add an event handler for the ViewSelectionChanged event.

When the active view changes, the handler checks the view type. It enables a button if the view is a resource view and disables the button if it isn't a resource view. Clicking the button gets the GUID of the selected resource and displays it in the app.

The example assumes your app has a reference to the jQuery library and that the following page controls are defined in the content div in the page body:

<input id="get-info" type="button" value="Get info" disabled="disabled" /><br />
<span id="message"></span>
(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, app-specific code can run.
            // Add a ViewSelectionChanged event handler.
            Office.context.document.addHandlerAsync(
                Office.EventType.ViewSelectionChanged,
                getActiveView);
            $('#get-info').click(getResourceGuid);

            // This example calls the handler on page load to get the active view
            // of the default page.
            getActiveView();
        });
    };

    // Activate the button based on the active view type of the document.
    // This is the ViewSelectionChanged event handler.
    function getActiveView() {
        Office.context.document.getSelectedViewAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    var viewType = result.value.viewType;
                    if (viewType == 6 ||   // ResourceForm
                        viewType == 7 ||   // ResourceSheet
                        viewType == 8 ||   // ResourceGraph
                        viewType == 15) {  // ResourceUsage
                        $('#get-info').removeAttr('disabled');
                    }
                    else {
                        $('#get-info').attr('disabled', 'disabled');
                    }
                    var output = String.format(
                        'View name: {0}<br/>View type: {1}',
                        result.value.viewName, viewType);
                    $('#message').html(output);
                }
            }
        );
    }

    // Get the GUID of the currently selected resource and display it in the app.
    function getResourceGuid() {
        Office.context.document.getSelectedResourceAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    $('#message').html('Resource GUID: ' + result.value);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

For a complete code sample that shows how to use a TaskSelectionChanged event handler in a Project app, see How to: Create your first task pane app for Project by using a text editor.

A checkmark (√) in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running apps for Office.

Office for Windows desktop

Office for Windows RT

Office Online
(in browser)

Project

Available in requirement sets

Minimum permission level

ReadWriteDocument

App types

Task pane

Library

Office.js

Namespace

Office

Version

Changes

1.0

Introduced

Show:
© 2015 Microsoft