Create Office 2019 - 2007 custom task panes
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 > Custom Office task panes

Custom task panes in Office 2019 - 2007

To allow further customization of Office applications, Microsoft introduced custom task panes in Office 2007 and supported them further in Office 2010, 2013, 2016 and 2019. Add-in Express allows you to create Office custom task panes by equipping the COM Add-in module with the TaskPanes property. Add a UserControl to your project, add an item to the TaskPanes collection of the add-in module, and set up the item by choosing the control in the ControlProgId property and filling in the Title property. Add your reaction to the OnTaskPaneXXX event series of the add-in module and the DockPositionStateChange and VisibleStateChange events of the task pane item. Use the OfficeColorSchemeChanged event and the OfficeColorScheme property to get the current Office color scheme.

Below is the detailed description of how to create a custom task pane with Add-in Express.

To add a new task pane, you add a UserControl to your project and populate it with controls. Then you add an item to the TaskPanes collection of the add-in module and specify its properties:

• Caption - the caption of your task pane (required!)
• Height, Width - the height and width of your task pane (applies to horizontal and vertical task panes, correspondingly)
• DockPosition - you can dock your task pane to the left, top, right, or bottom edges of the host application window
• ControlProgID - the UserControl just added

In Add-in Express, you work with the task pane component and task pane instances. The TaskPanes collection of the add-in module contains task pane components. When you set, say, the height or dock position of the component, these properties apply to every task pane instance that the host application shows. To modify a property of a task pane instance, you should get the instance itself. This can be done through the Item property of the component (in C#, this property is the indexer for the ADXTaskPane class); the property accepts a window object (such as Outlook.Explorer, Outlook.Inspector, Word.Window, etc) as a parameter and returns an AddinExpress.MSO.ADXTaskPane.ADXCustomTaskPaneInstance representing a task pane instance. For instance, the method below finds the currently active instance of the task pane in Outlook and refreshes it. For the task pane to be refreshed in a consistent manner, this method should be called in appropriate event handlers.

Private Sub RefreshTaskPaneInOutlookWindow(ByVal ExplorerOrInspector As Object)
   If Me.HostMajorVersion >= 12 Then
      Dim TaskPaneInstance As _
         AddinExpress.MSO.ADXTaskPane.ADXCustomTaskPaneInstance = _
            AdxTaskPane1.Item(ExplorerOrInspector)
      If Not TaskPaneInstance Is Nothing _
         And TaskPaneInstance.Visible Then
         Dim uc As UserControl1 = TaskPaneInstance.Control
         If Not uc Is Nothing Then _
           uc.InfoString = GetSubject(ExplorerOrInspector)
      End If
   End If
End Sub

The InfoString property just gets or sets the text of the Label located on UserControl1. The GetSubject method is shown below.

   Private Function GetSubject(ByVal ExplorerOrInspector As Object) _
      As String
      Dim mailItem As Outlook.MailItem = Nothing
      Dim selection As Outlook.Selection = Nothing
 
      If TypeOf ExplorerOrInspector Is Outlook.Explorer Then
         Try
            selection = CType(ExplorerOrInspector, _
               Outlook.Explorer).Selection
            mailItem = selection.Item(1)
         Catch
         Finally
            If Not selection Is Nothing Then _
               Marshal.ReleaseComObject(selection)
         End Try
      ElseIf TypeOf ExplorerOrInspector Is Outlook.Inspector Then
         Try
            mailItem = CType(ExplorerOrInspector, _
               Outlook.Inspector).CurrentItem
         Catch
         End Try
      End If
 
      If mailItem Is Nothing Then
         Return ""
      Else
         Dim subject As String = "The subject is: " + mailItem.Subject
         Marshal.ReleaseComObject(mailItem)
         Return subject
      End If
   End Function

The code of the GetSubject method emphasizes the following:

• The ExplorerOrInspector parameter was originally obtained through parameters of Add-in Express event handlers. That is why we do not release it (see Releasing COM objects).
• The selection and mailItem COM objects were created "manually" so they must be released.
• All Outlook versions fire an exception when you try to obtain the Selection object for a top-level folder, such as Personal Folders.

Below is another sample that demonstrates how the same things can be done in Excel or Word 2019, 2016, 2013, 2010 and 2007.

Imports AddinExpress.MSO
...
   Private Sub RefreshTaskPane()
      If Me.HostMajorVersion >= 12 Then
         Dim Window As Object = Me.HostApplication.ActiveWindow
         If Not Window Is Nothing Then
            RefreshTaskPaneInstance(AdxTaskPane1.Item(Window))
            Marshal.ReleaseComObject(Window)
         End If
      End If
   End Sub
 
   Private Sub RefreshTaskPaneInstance(ByVal TaskPaneInstance As _
      ADXTaskPane.ADXCustomTaskPaneInstance)
      If Not TaskPaneInstance Is Nothing Then
         Dim uc As UserControl1 = TaskPaneInstance.Control
         If uc IsNot Nothing And TaskPaneInstance.Window IsNot Nothing Then
            uc.InfoString = GetInfoString(TaskPaneInstance.Window)
         End If
      End If
   End Sub

The InfoString property mentioned above just updates the text of the label located on the UserControl. Please pay attention to Releasing COM objects in this code.