Advanced Outlook Regions and Task Panes
for Office 2019 - 2010 in VB.NET, C#, C++
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:
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:
Table 1. Events that occur before a form instance is created.
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:
Table 2. Events that occur before a form instance is embedded into a subpane.
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).
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:
When the region is in the minimized state, the user can choose any of the three options below:
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 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:
You can create a Ribbon or command bar button that allows the user to show the form that was previously hidden.
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).
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:
Table 3. Events in which 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).
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:
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:
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>.
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.
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.
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>.
To get an object corresponding to the host application's window that the form is shown for, use the following members:
The properties listed below return a COM object that you must release after use.
Table 4. Accessing the host application's window object from Add-in Express forms