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 Office application that it has completed its processing.
Remarks
For information on support in Excel, Word, and PowerPoint, see Add-in commands requirement sets.
The following outlines support information for Outlook.
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:
|
Property Details
source
Information about the control that triggered calling this function.
source:Source;Property Value
Remarks
The following outlines support information for Outlook.
Minimum permission level: restricted
Applicable Outlook mode: Compose or Read
Examples
// In this example, consider a button defined in an add-in manifest.
// The following is the XML manifest definition. Below it is the Teams
// manifest (preview) definition.
//
//
//
//
//
//
//
//
// testEventObject
//
//
//
// The Teams manifest (preview) definition is the following.
// Ellipses("...") indicate omitted properties.
//
// "extensions": [
// {
// ...
// "runtimes": [
// {
// "id": "CommandsRuntime",
// "type": "general",
// "code": {
// "page": "https://localhost:3000/commands.html",
// "script": "https://localhost:3000/commands.js"
// },
// "lifetime": "short",
// "actions": [
// {
// "id": "testEventObject",
// "type": "executeFunction",
// "displayName": "testEventObject"
// }
// ]
// }
// ],
// "ribbons": [
// {
// ...
// "tabs": [
// ...
// "groups": [
// ...
// "controls": [
// {
// "id": "eventTestButton",
// "type": "button",
// "label": "Perform an action",
// "icons": [
// {
// "size": 16,
// "file": "https://localhost:3000/assets/blue-icon-16.png"
// },
// {
// "size": 32,
// "file": "https://localhost:3000/assets/blue-icon-32.png"
// },
// {
// "size": 80,
// "file": "https://localhost:3000/assets/blue-icon-80.png"
// }
// ],
// "supertip": {
// "title": "Perform an action",
// "description": "Perform an action when clicked."
// },
// "actionId": "testEventObject"
// }
// ]
// ]
// ]
// }
// ]
// }
// ]
// The button has an id 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.
An on-send add-in in Outlook.
An online-meeting provider add-in in Outlook.
A note-logging add-in in Outlook on mobile devices.
completed(options?: EventCompletedOptions): void;Parameters
Optional. In Outlook, an object that specifies the behavior of an on-send add-in, online-meeting provider add-in, or note-logging mobile add-in when it completes processing an event.
Returns
void
Remarks
The following outlines support information for Outlook.
Minimum permission level: restricted
Applicable Outlook mode: Compose or Read
Important:
The
optionsparameter only applies to Outlook add-ins. It was introduced in Mailbox 1.8. Although Outlook on Android and on iOS support up to Mailbox 1.5, theoptionsparameter is supported in online-meeting provider and note-logging mobile add-ins. For more information on API support in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.Event-based activation and integrated spam-reporting add-ins use a different event object to signal when they've completed processing an event. For more information, see Office.MailboxEvent.
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 checkMessage function was registered as an event handler for ItemSend.
function checkMessage(event) {
// Get the item being sent.
const outgoingMsg = Office.context.mailbox.item;
// Check if subject contains "BLOCK".
outgoingMsg.subject.getAsync(function (result) {
// Subject is in `result.value`.
// If search term "BLOCK" is found, don't send the message.
const notFound = -1;
const allowEvent = (result.value.indexOf('BLOCK') === notFound);
event.completed({ allowEvent: allowEvent });
});
}