Office.AddinCommands.Event interface

The Event object is passed as a parameter to add-in functions invoked by function 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

See Add-in commands requirement sets for more support information.

Minimum permission level (Outlook): Restricted

Applicable Outlook mode: Compose or Read

Properties

source

Information about the control that triggered calling this function.

Methods

completed(options)

Indicates that the add-in has completed processing and will automatically be closed.

This method must be called at the end of a function which was invoked by the following:

  • A function command button (that is, an add-in command defined with an Action element, where the xsi:type attribute is set to ExecuteFunction).

  • An event defined in the LaunchEvent extension point. For example, an OnMessageSend event.

  • An event defined in the Events extension point. For example, an ItemSend event.

Property Details

source

Information about the control that triggered calling this function.

source:Source;

Property Value

Remarks

This property is supported in Outlook only in requirement set Mailbox 1.3 and later.

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".
    const 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.
    const buttonId = event.source.id;

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

    event.completed();
}

Method Details

completed(options)

Indicates that the add-in has completed processing and will automatically be closed.

This method must be called at the end of a function which was invoked by the following:

  • A function command button (that is, an add-in command defined with an Action element, where the xsi:type attribute is set to ExecuteFunction).

  • An event defined in the LaunchEvent extension point. For example, an OnMessageSend event.

  • An event defined in the Events extension point. For example, an ItemSend event.

completed(options?: EventCompletedOptions): void;

Parameters

options
Office.AddinCommands.EventCompletedOptions

Optional. An object that specifies behavior options for when the event is completed.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: Restricted

Applicable Outlook mode: Compose or Read

Note: The options parameter was introduced in Mailbox 1.8.

Examples

// For the following example, the processItem function is
// defined in the FunctionFile referenced from the add-in manifest,
// and maps to the FunctionName of the action in the associated button control.
function processItem(event) {
    // Do some processing

    event.completed();
}
// In this example, the function is registered as an event handler for the OnAppointmentSend event.
// It checks whether a location is specified in an appointment before it's sent.
function onAppointmentSendHandler(event) {
    Office.context.mailbox.item.location.getAsync({ asyncContext: event }, asyncResult => {
        let event = asyncResult.asyncContext;
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            // If the add-in is unable to retrieve the appointment's location, the appointment isn't sent.
            event.completed({ allowEvent: false, errorMessage: "Failed to get the appointment's location." });
            return;
        }

        if (asyncResult.value === "") {
            // If no location is specified, the appointment isn't sent and the user is alerted to include a location.
            event.completed({ allowEvent: false, errorMessage: "Don't forget to add a meeting location." });
            return;
        } else {
            // If a location is specified, the appointment is sent.
            event.completed({ allowEvent: true });
        }
    });
}