Add-in Express™
for Microsoft® Office and .netAdd-in Express Home > Add-in Express for Office and .NET > Online Guide > Add-in Express components > UI mechanics for advanced Outlook regions and advanced Office task panes
UI mechanics for advanced Outlook regions and advanced task panes
Region states and UI-related properties and events
As mentioned in an Absolute must-know, the <Manager> creates instances of the <Form>. An instance
of the <Form> (further on the instance is referenced as form) is considered visible if it is embedded into the specified sub-pane 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
sub-pane hide it; anyway, in this case, <Form>.Visible returns true. To prevent embedding the form into a sub-pane, you can set <Form>.Visible to
false in the event named ADXBeforeFormShow in Outlook, ADXBeforeTaskPaneShow in Excel, Word, and PowerPoint. When the form is shown in a sub-pane, 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 sub-pane, <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 sub-pane for the very first time and no other
forms have been shown in that sub-pane before.
You can change the state of your form at run-time using the <Form>.RegionState property. When showing your Outlook form in
certain sub-panes, 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>
- 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.
Drag-n-drop and Advanced Outlook regions
The form can be dragged only if 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). The form is dragged in the VS style, see the screenshot below.
Showing / hiding form instances programmatically
In Excel and PowerPoint, a single instance of the <Form> is always created for a given <Item> because these applications show
documents in a single main window. On the contrary, Word is an application that normally shows multiple windows, and in this situation,
the Word Task Panes Manager creates one instance of the task pane for every document 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 your custom task pane, 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. Note that in Excel and PowerPoint an only
instance of the <Form> is always created for a given <Item>.
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, call its Hide method.
You can check that a form is not available in the UI (say, you cancelled the event or set <Form>.Visible = False in
the 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 ShowTaskPane method of the <Item>
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 Activate 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 Splitter property of the <Item>. 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 stored in 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 - 2010 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 start-up, 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 <Position> property of the <Item> 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>.
Back to Add-in Express for Office and .NET homepage | 
