Office.AddinCommands.Event interface

The event object is passed as a parameter to add-in functions invoked by UI-less command buttons. The object allows the add-in to identify which button was clicked and to signal the host that it has completed its processing.

Remarks

Add-in typeContent, task pane, Outlook
Minimum permission levelRestricted
Applicable Outlook modeCompose or Read

Properties

source

Information about the control that triggered calling this function.

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this property.

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Outlook Y (Mailbox 1.3)

Methods

completed(options)

Indicates that the add-in has completed processing that was triggered by an add-in command button or event handler.

This method must be called at the end of a function which was invoked by an add-in command defined with an Action element with an xsi:type attribute set to ExecuteFunction. Calling this method signals the host client that the function is complete and that it can clean up any state involved with invoking the function. For example, if the user closes Outlook before this method is called, Outlook will warn that a function is still executing.

This method must be called in an event handler added via Office.context.mailbox.addHandlerAsync after completing processing of the event.

[ API set: Mailbox 1.3 ]

Property Details

source

Information about the control that triggered calling this function.

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this property.

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Outlook Y (Mailbox 1.3)

source: Source;

Property Value

Examples

// In this example, consider a button defined in an add-in manifest as follows:
<Control xsi:type="Button" id="eventTestButton">
    <Label resid="eventButtonLabel" />
    <Tooltip resid="eventButtonTooltip" />
    <Supertip>
        <Title resid="eventSuperTipTitle" />
        <Description resid="eventSuperTipDescription" />
    </Supertip>
    <Icon>
        <bt:Image size="16" resid="blue-icon-16" />
        <bt:Image size="32" resid="blue-icon-32" />
        <bt:Image size="80" resid="blue-icon-80" />
    </Icon>
    <Action xsi:type="ExecuteFunction">
        <FunctionName>testEventObject</FunctionName>
    </Action>
</Control>
// The button has an id attribute set to eventTestButton, and will invoke
// the testEventObject function defined in the add-in.
// That function looks like this:
function testEventObject(event) {
    // The event object implements the Event interface

    // This value will be "eventTestButton"
    var buttonId = event.source.id;

    // Signal to the host app that processing is complete.
    event.completed();
}
// Function is used by two buttons:
// button1 and button2
function multiButton (event) {
    // Check which button was clicked
    var buttonId = event.source.id;

    if (buttonId === 'button1') {
        doButton1Action();
    }
    else {
        doButton2Action();
    }

    event.completed();
}

Method Details

completed(options)

Indicates that the add-in has completed processing that was triggered by an add-in command button or event handler.

This method must be called at the end of a function which was invoked by an add-in command defined with an Action element with an xsi:type attribute set to ExecuteFunction. Calling this method signals the host client that the function is complete and that it can clean up any state involved with invoking the function. For example, if the user closes Outlook before this method is called, Outlook will warn that a function is still executing.

This method must be called in an event handler added via Office.context.mailbox.addHandlerAsync after completing processing of the event.

[ API set: Mailbox 1.3 ]

completed(options?: any): void;

Parameters

options
any

Optional. An object literal that contains one or more of the following properties. allowEvent: A boolean value. When the completed method is used to signal completion of an event handler, this value indicates of the handled event should continue execution or be canceled. For example, an add-in that handles the ItemSend event can set allowEvent = false to cancel sending of the message.

Returns

void

Remarks

Minimum permission levelRestricted
Applicable Outlook modeCompose or read

Support details

A capital Y 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 Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Excel Y Y Y
Outlook Y (Mailbox 1.3)
PowerPoint Y Y Y
Word Y Y Y

Examples

function processItem (event) {
    // Do some processing

    event.completed();
}

// In the following example, the checkMessage function has
// been registered as an event handler for ItemSend.
function checkMessage(event) {
    // Get the item being sent
    var outgoingMsg = Office.context.mailbox.item;

    // Check if subject contains "BLOCK"
    outgoingMsg.subject.getAsync(function (result) {
        // Subject is in result.value
        if (result.value.indexOf('BLOCK') != -1) {
            // Value is found, stop send
            event.completed({allowEvent = false});
        } else {
            // Value wasn't found, allow send
            event.completed({allowEvent = true});
        }
    });
}