Add-in Express™
for Microsoft® Office and .netAdd-in Express Home > Add-in Express .NET > Online Guide > Custom task panes Custom task panes
Add-in Express allows developing COM add-ins that show custom panes, also referred as custom forms, in Outlook, Excel, Word, and PowerPoint, versions 2000 - 2007. And here are the three main points you should know about:
- There are application-specific <Manager> components; every <Manager> component provides a collection; each <Item> from the collection binds a <Form> (an application-specific descendant of System.Windows.Forms.Form) to the visualization and context (Outlook-only) settings.
- You never create an instance of a <Form> in the way you create an instance of System.Windows.Forms.Form; instead, the <Manager> creates instances of the <Form> for you; the instances are created either automatically or at your request.
- The Visible property of a <Form> instance is true, when the instance is embedded into a window region (as specified by the visualization settings) regardless of the actual visibility of the instance; the Active property of the <Form> instance is true, when the instance is shown on top of all other instances in the same region.
Note. Anywhere on this page, as well as on other pages, a term in angle brackets, such as <Manager> or <Form> above, specifies a component, class, or class member, the actual name of which is application-dependent.
Obviously, all Office applications have different window structures. Accordingly, Add-in Express provides a number of application-specific options for embedding your forms.
Word, Excel and PowerPoint task panes
These Office applications allow showing your forms in four regions; the regions are docked to the four edges of the application’s main window. The names of the regions are Left, Top, Right, and Bottom (see the Position property of the <Item>).
Advanced custom task panes in Excel 2000 - 2007
The only Excel version that allows adding custom task panes is Excel 2007. To be more precise, VSTO 2005 (not SE!) as well as VSTO included in VS 2008 allow customizing Excel 2003 workbooks and templates with action panes, but not with custom task panes. Now, with Add-in Express, you can create custom task panes for your COM add-ins in Excel 2000 - 2007.
For more details about creating custom task panes in Excel see Building custom task panes in Excel 2000 - 2007
Advanced custom task panes in Word 2000 - 2007
Microsoft provides custom task panes for Word 2007 only. Add-in Express allows your COM add-ins to create custom task panes in Word 2000, XP, 2003 and Word 2007. To achieve this, Add-in Express provides ADXWordTaskPane, a descendant of System.Windows.Forms.Form. This base class implements the functionality that is required to embed your .NET form into Word. To add such a form to your add-in project, you choose the corresponding item in the Add New Item dialog. ADXWordTaskPanesManager, the Word Task Pane Manager component that you add to the add-in module using its context menu or Commands of the Add-in Module, is the other part of the technology. Then you add an item to the Items collection of the manager, bind the item to the task pane using the item's TaskPaneClassName property, and specify the position, at which the task pane will be shown.
If you need a sample of creating custom task panes in Word, see Developing custom task panes in Word 2000 - 2007
Advanced custom task panes in PowerPoint 2000 - 2007
Custom task panes are also available for COM add-ins in PowerPoint. The following three things constitute the base of the Add-in Express Task Panes technology:
- ADXPowerPointTaskPane form, a descendant of System.Windows.Forms.Form; you add this form to your add-in project by choosing the corresponding item in the Add New Item dialog.
- ADXPowerPointTaskPanesManager manager; you add the Word Task Pane Manager component to the add-in module using its context menu or commands of the Add-in Module.
- ADXPowerPointTaskPanesCollectionItem item, a member of the Items collection of the manager; you bind the item to the form using the item's TaskPaneClassName property, and specify the position of the task pane by using the Position property.
For more details about building a custom task pane in PowerPoint, see the following sample: Creating a custom task pane in PowerPoint 2000 - 2007
For new features and capabilities of task panes in Add-in Express 2009, visit our technical blog:
Outlook regions
With Add-in Express you can add your custom forms practically to any Outlook region, including regions around the list of mails, tasks, contacts, appointments; Reading Pane, Navigation Pane and To-Do bar. For more information, please see:
Advanced Outlook regions in Add-in Express 2009:
The UI, related properties and events of task panes
As mentioned above, the <Manager> creates instances of the <Form>. An instance of the <Form> (further on it is referenced as form) is considered visible if it is embedded into a region. The task pane may be actually invisible either due to the region state (see below) or because other forms in the same region hide it; anyway in this case, <Form>.Visible returns true. Before the task pane becomes actually visible in a region, a cancellable event occurs; the event name is ADXBeforeFormShow in Outlook, ADXBeforeTaskPaneShow in Excel, Word, and PowerPoint. When the pane is shown in a region, the Activated event occurs and <Form>.Active becomes true. When the user moves the focus onto the pane, the <Form> generates the ADXEnter event. When the task pane loses focus, the ADXLeave event occurs. When the form becomes invisible (actually), it generates the Deactivate event. When the corresponding <Manager> removes the pane from its region, <Form>.Visible becomes false and the form generates the ADXAfterFormHide event in Outlook, ADXAfterTaskPaneHide event in Excel, Word, and PowerPoint.
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):
  
These states are reflected in the corresponding values of the DefaultRegionState property of the <Item> - Hidden, Normal and Minimized.
When the region is in the minimized state, the user can click on the splitter and the region 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 moving 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; if the event isn't cancelled, the Deactivate event occurs, then the task pane is being deleted from the region (<Form>.Visible = false) and finally, the <ADXAfterPaneHide> 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 form 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 two options below:
- Return 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 overlaps a part of the Outlook window near the form region; this also raises the Activated event of the form and sets the Active property of the form to true.
The Close button and the header
The Close button is shown if the CloseButton property of the <Item> is true. 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 the AlwaysShowHeader property of the <Item> 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.
Showing / hiding form instances programmatically
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.
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 ApplyTo method of the <Item>; the method accepts the parameter, which is either Outlook.Explorer or Outlook.Inspector
- For Excel, Word, and PowerPoint, you call the ShowTaskPane method of the <Item>
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 custom task panes
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 custom task pane 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 task pane 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 task pane 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.
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.
Back to Add-in Express .NET homepage |