Advanced Outlook Regions and Task Panes
for Office 2019 - 2010 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 > UI mechanics for advanced Outlook regions and Office task panes

UI mechanics of advanced regions and task panes

This page lets you get the insight of advanced Outlook regions and Office task panes. It covers the following aspects:

• Outlook region states and UI-related properties and events
• Normal, hidden and minimized task panes
• The header and the Close button
• Repositioning the form in the host application's UI
• Accessing a form instance
• Controlling form visibility
• Resizing the forms
• Coloring up the form
• Tuning the settings at run time
• What window the pane is shown for

Outlook region states and UI-related properties and events

As mentioned in an Absolute must-know, the <Manager> creates instances of the <Form>. To prevent an instance from being created you cancel one of the events listed below:

An instance of the <Form> (further on the instance is referenced as form) is considered visible if it is embedded into the specified subpane of an Outlook, Excel, Word or PowerPoint window. The form may be actually invisible either due to the region state (see below) or because other forms in the same subpane hide it; anyway, in this case, <Form>.Visible returns true.

To prevent embedding the form into a subpane of Excel, Word, and PowerPoint, you can set <Form>.Visible=false in these events:

When the form is shown in a subpane, the Activated event occurs and <Form>.Active becomes true. When the user moves the focus onto the form, the <Form> generates the ADXEnter event. When the form loses focus, the ADXLeave event occurs. When the form becomes invisible (actually), it generates the Deactivate event. When the corresponding <Manager> removes the form from the subpane, <Form>.Visible becomes false and the form generates the ADXAfterFormHide event in Outlook and the ADXAfterTaskPaneHide event in Excel, Word, and PowerPoint.

In accordance to the value that you specify for the <Item>.DefaultRegionState property, the form may be initially shown in any of the following region states: Normal, Hidden (collapsed to a 5px wide strip), Minimized (reduced to the size of the form caption).

Normal, hidden and minimized task panes

Your custom task pane, or custom form, may be initially shown in any of the following region states: normal, hidden (collapsed to a 5px wide strip), minimized (reduced to the size of the form caption):

Note however that DefaultRegionState will only work when you show the form in that subpane for the very first time and no other forms have been shown in that subpane before.

You can change the state of your form at run time using the <Form>.RegionState property. When showing your Outlook form in certain subpanes, you may need to show the native Outlook view or form that your form overlays; use the ADXOlForm.ActivateStandardPane() method.

When the region is in the hidden state, i.e. when it is collapsed to a 5px wide strip, the user can click on the splitter and the region will be restored (it will go to the normal state).

When the region is in the normal state, the user can choose any of the options below:

• change the region size by dragging the splitter; this raises size-related events of the form;
• hide the form by clicking on the "dotted" mini-button or by double-clicking anywhere on the splitter; this fires the Deactivate event of the <Form>; this option is not available for the end user if you set ADXOlFormsCollectionItem.IsHiddenStateAllowed = False;
• close the form by clicking on the Close button in the form header; this fires the ADXCloseButtonClick event of the <Form>. The event is cancellable, see The header and the Close button; if the event isn't cancelled, the Deactivate event occurs, then the pane is being removed from the region (<Form>.Visible = false) and finally, the <ADXAfterFormHide> event of the <Form> occurs;
• show another form by clicking the header and choosing an appropriate item in the popup menu; this fires the Deactivate event on the first form and the Activated event on the second form
• transfer the region to the minimized state by clicking the arrow in the right corner of the form header; this fires the Deactivate event of the form.

When the region is in the minimized state, the user can choose any of the three options below:

• restore the region to the normal state by clicking the arrow at the top of the slim profile of the form region; this raises the Activated event of the form and changes the Active property of the form to true;
• expand the form itself by clicking on the form's button; this opens the form so that it overlays a part of the Office application's window near the form region; this also raises the Activated event of the form and sets the Active property of the form to true;
• drag an Outlook item, Excel chart, file, selected text, etc. onto the form button; this fires the ADXDragOverMinimized event of the form; the event allows you to check the object being dragged and to decide if the form should be restored.

You can change the state of your form at run time using the <Form>.RegionState property. When showing your Outlook form in some layouts, you need to show the standard form that your form overlays; use the ADXOlForm.ActivateStandardPane() method. Also, you can use the DefaultRegionState property of the <Item>. Note that this property will work for you when you show the form in that region for the very first time and no other forms have been shown in that region before.

When the region is in the hidden state, the user can click on the splitter and the region will be restored (it will go to the normal state).

The header and the Close button

The header is always shown when there are two or more forms in the same region. When there is just one form in a region, the header is shown only if <Item>.AlwaysShowHeader is set to true.

The Close button is shown if <Item>.CloseButton is true. Clicking on the Close button in the form header fires the ADXCloseButtonClick event of the <Form>, the event is cancellable:

Private Sub ADXOlForm1_ADXCloseButtonClick(ByVal sender As System.Object, _
    ByVal e As AddinExpress.OL.ADXOlForm.ADXCloseButtonClickEventArgs) _
    Handles MyBase.ADXCloseButtonClick
    e.CloseForm = False
End Sub

You can create a Ribbon or command bar button that allows the user to show the form that was previously hidden.

Repositioning the form in the host application's UI

You can let the user drag the form to a new position. This requires that all of the following conditions are met A) ) it has the header (see The header and the Close button), B) you set ADXOlFormsCollectionItem.IsDragDropAllowed=True and C) you specify the positions in which your form can be dropped (see the ADXOlFormsCollectionItem.ExplorerAllowedDropRegions property).

Accessing a form instance

Add-in Express forms (panes) are based on the windowing of the corresponding Office application – Excel, Word, Outlook, and PowerPoint. At run time, Add-in Express intercepts the messages the application sends to its windows and reacts to the messages so that your form is shown, hidden, resized, etc. along with the application's windows.

In Excel 2000-2010 and PowerPoint 2000-2007, a single instance of the <Form> is always created for a given <Form> because these applications show documents in a single main window. Word is an application that shows multiple windows, and in this situation, the Word Task Panes Manager creates one instance of the task pane for every document window opened in Word.

Outlook is a specific host application. It shows several instances of two window types simultaneously. In addition, the user can navigate through the folder tree and select, create and read several Outlook item types. Accordingly, an ADXOlFormsCollectionItem can generate and show several instances of ADXOlForm at the same time. Find more details on managing custom panes in Outlook in Advanced Outlook regions.

To access the form, which is currently active in Excel or PowerPoint, you use the TaskPaneInstance property of the <Item>; in Word, the property name is CurrentTaskPaneInstance; in Outlook, it is the GetCurrentForm method. To access all instances of the <Form> in Word, you use the TaskPaneInstances property of ADXWordTaskPanesCollectionItem; in Outlook, you use the FormInstances method of ADXOlFormsCollectionItem (find more details in Form region Instancing).

It is essential that Add-in Express panes are built on the windowing of the host application, not on the events of the application's object model. This means that getting an instance of an Add-in Express pane in a certain event may result in getting null (Nothing in VB.NET) if the call is issued before the pane is shown or after it is hidden. For instance, it is often the case with WindowActivate/WindowDeactivate in Excel, Word, and PowerPoint. Below is a list of events where Add-in Express panes may be inaccessible:

So, you may encounter a problem if your add-in retrieves a pane instance in an event above. To bypass this problem, we suggest modifying the code of the add-in so that it gets notified about a pane instance being shown or hidden (instead of getting the pane instance by handling the events above).

Use the ADXBeforeTaskPaneShow event of the task pane class (Excel, Word, and PowerPoint) and the ADXOlForm.ADXBeforeFormShow (Outlook) event to be notified about the specified pane instance being shown. When the form becomes hidden you'll get ADXOlForm.ADXAfterFormHide (Outlook) and the ADXAfterTaskPaneHide event of the task pane class (Excel, Word, and PowerPoint).

Controlling Form Visibility

To prevent a form from being displayed in the host application's window, you can set <Form>.Visible to false in the events listed in Table 2 (see above).

By setting the Enabled property of an <Item> to false, you delete all form instances created for that <Item>. To hide (i.e. to remove from the region) any given form, set its Visible property to false.

You can check that a form is not available in the UI (say, you cancelled the <BeforInstanceCreate> event or set <Form>.Visible = False in the <BeforeFormShow> event or the user closed it) by checking the Visible property of the form:

    Dim Pane As ADXWordTaskPane1 = _
        TryCast(Me.AdxWordTaskPanesCollectionItem1.CurrentTaskPaneInstance, _
            ADXWordTaskPane1)
    Dim DoesPaneExist As Boolean
    If Pane IsNot Nothing Then
        DoesPaneExist = Pane.Visible
    Else
        DoesPaneExist = False
    End If

If a task pane wasn't created for some reason (say, you cancelled the <BeforInstanceCreate> or <BeforeFormShow> events), then you can show it in one step:

• For Outlook, you call the ADXOlFormsCollectionItem.ApplyTo() method accepting the parameter which is either Outlook.Explorer or Outlook.Inspector object;
• For Excel, Word, and PowerPoint, you call the <Item>.ShowTaskPane() method.

The methods above also transfer the region that shows the form to the normal state.

If the Active property of your form is false, that is your form is hidden by other forms in the region, then you can call the Activatee method of the <Form> to show the form on top of all other forms in that region. Note that if the region was in either minimized or hidden state, calling Activate will also transfer it to the normal state.

Note that your form doesn't restore its Active state in subsequent sessions of the host application in regions that show several forms. In other words, if several add-ins show several forms in the same region and the current session finishes with a given form at on top of the stack of forms in that region, the subsequent start of the host application may show some other form as active. This is because events are given to add-ins in an unpredictable order. When dealing with several forms of a given add-in, they are created in the order determined by their locations in the <Items> collection of the <Manager>.

In Outlook, due to context-sensitivity features provided by the <Item>, an instance of your form will be created whenever the current context matches that specified by the corresponding <Item>.

Resizing the forms

There are two values of the <Item>.Splitter property. The default one is Standard. This value shows the splitter allowing the user to change the form size as required. The task pane size is saved to the registry so that the size is restored whenever the user starts the host application.

You can only resize your form programmatically, if you set the Splitter property to None. Of course, no splitter will be shown in this case. Changing the Splitter property programmatically doesn't affect a form currently loaded to its region (that is, having Visible = true). Instead, it will be applied to any newly shown form.

If the form is shown in a given region for the first time and no forms were ever shown in this region, the form will be shown using the appropriate dimensions that you set at design time. On subsequent add-in starts, the form will be shown using the dimensions set by the user.

Coloring up the form

By default, the background color of the form is set automatically to match the current Office 2007 - 2019 color scheme. To use the background color of your own in these Office versions (as well as in Office 2003), you need to set <Item>.UseOfficeThemeForBackground = True.

Tuning the settings at run time

To add/remove an <Item> to / from the collection and to customize the properties of an <Item> at add-in startup, you use the <Initialize> event of the <Manager>; the event's name is OnInitialize for Outlook and ADXInitalize for Excel, Word and PowerPoint.

Changing the Enable, Cached (Outlook only), <FormClassName> properties at run time deletes all form instances created by the <Item>.

Changing the InspectorItemTypes, ExplorerItemTypes, ExplorerMessageClasses, ExplorerMessageClass, InspectorMessageClasses, InspectorMessageClass, FolderNames, FolderName properties of the ADXOlFormsCollectionItem deletes all non-visible form instances.

Changing the <Item>.<Position> property changes the position for all visible form instances.

Changing the Splitter and Tag properties of the <Item> doesn't do anything for the currently visible form instances. You will see the changed splitter when the <Manager> shows a new instance of the <Form>.

What window the pane is shown for

To get an object corresponding to the host application's window that the form is shown for, use the following members: