Components to customize Office 2019 - 2000
in VB.NET, C#, C++

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Add-in Express components > Other components: events, Outlook UI, smart tags, RTD

Add-in Express components

Office events

Application-level events

In the Add-in Express Toolbox, there is the Add Events command that creates specified events components on the module. The events components allow accessing application-level events for all Office applications. You use event handlers of such an event component to respond to events of the host application. You may need to process other events provided by Outlook and Excel. If this is the case, see Event classes.

Application-level events

Event classes

Outlook and Excel differ from other Office applications because they have event-raising objects not only at the topmost level of their object models. These exceptions are the Folders and Items as well as all item types (MailItem, TaskItem, ContactItem, etc.) in Outlook and the Worksheet class in Excel. Add-in Express events classes ease the pain of handling such events in a version-independent way. The Add-in Express event classes also handle releasing of COM objects required for their functioning.

At design time, you add an Add-in Express events class to the project (see Step 13. Handling events of Outlook Items Object and Step 10. Handling Excel worksheet events). You use this class to implement a set of event handling rules for a given event source type. To implement another set of event handling rules for the same event source type, you add another events class to your project. For example, if the business logic is different for the Inbox and Sent Items folders in Outlook, use two events classes to handle the events of the Items collection: one for the Inbox folder and another one for the Sent Items.

At run time, you connect an Add-in Express event class instance to an event source using its ConnectTo method. To disconnect the Add-in Express event class from the event source you use the RemoveConnection method. To apply the same business rules to another event source of the same type (say, to items of another folder), you create a new instance of the same event class.

As mentioned above, the Outlook object model provides item-level events. To handle such events, you need to open the Add Item dialog of your add-in project and add an Outlook Item (not Items!) Events class to your project. What follows below is a code fragment from the sample project ReplyInHtmlFormat. The fragment demonstrates handling the Reply and ReplyAll events of an Outlook.MailItem object and connecting to events of a MailItem representing the response email. You can download the complete project: C# - here, VB.NET - here.


Imports Outlook = Microsoft.Office.Interop.Outlook
Imports System.Runtime.InteropServices

'Add-in Express Outlook Item Events Class
Public Class OriginalEmailEvents
    Inherits AddinExpress.MSO.ADXOutlookItemEvents

    Public Overrides Sub ProcessReply(ByVal Response As Object, _
        ByVal E As AddinExpress.MSO.ADXCancelEventArgs)
        ConnectToResponseItemEvents(Response)
    End Sub
    Public Overrides Sub ProcessReplyAll(ByVal Response As Object, _
        ByVal E As AddinExpress.MSO.ADXCancelEventArgs)
        ConnectToResponseItemEvents(Response)
    End Sub

    Dim responseEmailEvents As ResponseEmailEvents = Nothing
    Private Sub ConnectToResponseItemEvents(response As Object)
        ' response is a COM object represeting the response email. Add-in 
        ' Express releases this COM object as soon as the corresponding event 
        ' handler call is completed. Since you can't get events from a released
        ' COM object, you need to get a COM object that won't be controlled by 
        ' Add-in Express. To do this, you call the MailItem.GetInspector 
        ' property and then get the COM object by calling Inspector.CurrentItem
        Dim inspector As Outlook._Inspector = CType(response, _
            Outlook._MailItem).GetInspector
        Dim responseEmail As Outlook._MailItem = _
            CType(inspector.CurrentItem, Outlook._MailItem)        
        ' inspector and responseEmail contain COM objects that you must release
        ' as soon as you don't need them. Since you don't need inspector any
        ' longer, you release it here:
        Marshal.ReleaseComObject(inspector) : inspector = Nothing
        ' Then connect to the events of the response email
        If (responseEmailEvents IsNot Nothing) Then 
            responseEmailEvents.RemoveConnection()
        End If
        responseEmailEvents = New ResponseEmailEvents(Me.Module)
        responseEmailEvents.ConnectTo(responseEmail, True)
        ' the responseEmail COM object is passed to ResponseEmailEvents; 
        ' it is released in the ResponseEmailEvents.ProcessOpen method
    End Sub

Intercepting keyboard shortcuts

Every Office application provides built-in keyboard combinations that allow shortening the access path for commands, features, and options of the application. Add-in Express allows adding custom keyboard combinations and processing both custom and built-in ones.

Add the component onto ADXAddinModule, choose the keyboard shortcut you need in the ShortcutText property, set the HandleShortCuts property of the Add-in Express Module to true and process the Action event of the KeyboardShortcut component.

Outlook UI components

Outlook Bar Shortcut Manager component

Outlook provides us with the Outlook Bar (Navigation Pane since Outlook 2003). The Outlook Bar displays Shortcut groups consisting of Shortcuts that you can target a Microsoft Outlook folder, a file-system folder, or a file-system path or URL. You use the Outlook Bar Shortcut Manager to customize the Outlook Bar with your shortcuts and groups.

This component is available for ADXAddinModule. Use the Groups collection of the component to create a new shortcut group. Use the Shortcuts collection of a short group for creating a new shortcut. To connect to an existing shortcut or shortcut group, set the Caption properties of the corresponding ADXOlBarShortcut and / or ADXOlBarGroup components equal to the caption of the existing shortcut or shortcut group. Please note, there are no other ways to identify the group or shortcut.

That is why your shortcuts and shortcut groups must be named uniquely for Add-in Express to remove them (and not those with the same names) when the add-in is uninstalled. That is why you have to do this yourself. Depending on the type of its value, the Target property of the ADXOlBarShortcut component allows you to specify different shortcut types. If the type is MAPIFolder, the shortcut represents a Microsoft Outlook folder. If the type is a String, the shortcut represents a file-system path or a URL. No events are available for these components.

Outlook Property Page component

Outlook allows extending its Options dialog with custom pages. You see this dialog when you choose Tools | Options menu. In addition, Outlook allows adding such a page to the Folder Properties dialog. You see this dialog when you choose the Properties item in the folder context menu. You create such pages using the Outlook Property Page component.

In Visual Studio, open the Add New Item dialog and choose the Outlook Options Page item to add a class to your project. This class is a descendant of the System.Windows.Forms.UserControl class. It allows creating Outlook property pages using its visual designer. Just set up the property page properties, place your controls onto the page, and add your code. To add this page to the Outlook Options dialog, select the name of your control class in the PageType combo of ADXAddinModule and enter some characters into the PageTitle property.

To add a page to the Folder Properties dialog for a given folder(s), you use the FolderPages collection of the Add-in Express module. Run its property editor and add an item (of the ADXOlFolderPage type). You connect the item to a given property page through the PageType property. Note, the FolderName, FolderNames, and ItemTypes properties of the ADXOlFolderPage component work in the same way as those of Outlook-specific command bars.

Specify reactions required by your business logics in the Apply and Dirty event handlers. Use the OnStatusChange method to raise the Dirty event, the parameters of which allow marking the page as Dirty.

Smart Tag component

The Kind property of the ADXSmartTag component allows you to choose one of two text recognition strategies: either using a list of words in the RecognizedWords string collection or implementing a custom recognition process based on the Recognize event of the component. Use the ActionNeeded event to change the Actions collection according to the current context. The component raises the PropertyPage event when the user clicks the Property button in the Smart Tags tab (Tools / AutoCorrect Options menu) for your smart tag.

RTD Topic component

Use the String## properties to identify the topic of your RTD server. To handle RTD Server start-up situations nicely, specify the default value for the topic and, using the UseStoredValue property, specify, if the RTD function in Excel returns the default value (UseStoredValue = false) or doesn't change the displayed value (UseStoredValue = true). The RTD Topic component provides you with the Connect, Disconnect, and RefreshData events. The last one occurs (for enabled topics only) whenever Excel calls the RTD function.

Advanced Outlook regions <<

>> Deploying Office add-ins