Advanced Outlook form regions for Outlook 2013 – 2000

Outlook is one of the pillars of Microsoft Office development. In fact, it is the most popular target of Office developers. Users of Outlook eventually proclaim, “I live in Outlook”… meaning all their essential information resides within it. Each day, it is the first app they open and it is the last one they close.

As great as Outlook is, it was not designed to meet 100% of any one user’s needs. Therefore, users constantly think of ideas for how we developers can “trick it out”. And what do they want? They want custom Outlook forms!

They want forms here…
They want forms there…
They want forms everywhere!

The Add-in Express toolset allows you to build custom Outlook view and form regions and put them just about anywhere within Outlook. In my previous article, I discussed advanced Outlook view regions that display within the Outlook Explorer window.

Today, I’ll discuss advanced Outlook form regions that display in the Outlook Inspector window:

• What are advanced Outlook form regions?
• InspectorRegion region
• CompleteReplacement region
• How to create a custom Outlook form region
• Outlook form regions features and capabilities
• How to enumerate / access Outlook form regions
• How to delete / remove an Outlook form
• Useful events
• How to access form items

What are advanced Outlook form regions?

They are custom forms that display in the Outlook Inspector windows. You use them to display additional content or to replace Outlook’s default Inspector page with your own. Advanced Outlook form regions provided by Add-in Express finish the job Microsoft started by introducing Outlook Form Regions in Outlook 2007.

Add-in Express Outlook form windows are descendants of the WinForm. This means you can basically create WinForm, design it to your preferences, and display it. But ours have almost no bugs and more features. And our advanced Outlook form regions work on all versions of Outlook 2013, 2010, 2007 and 2003.

What are these features? Let’s take a look.

Display in four regions

Advanced Outlook form regions can display in your choice four separate regions:

• LeftSubpane
• TopSubpane
• RightSubpane
• BottomSubpane

They can display within the Inspector window an e-mail, contact, appointment, task, etc. They are versatile.

The InspectorRegion region

The InspectorRegion displays your Outlook form region “under” the main page of the Inspector window. It displays a header area that resides just beneath the Outlook ribbon. This header area contains a menu that allows users to switch between your form and the default page.

As the menu implies, you can have more than one Outlook form region assigned to an Inspector window. In this scenario, we take care of it and list all forms in the menu… making it easy for the user to toggle between the available forms and the main Inspector pane.

The CompleteReplacement region

The CompleteReplacement region is the same as the InspectorRegion except:

1. It does not display the header area or the menu.
2. Users cannot toggle between this region and the default Inspector pane.
3. The region activates automatically. It does not show the default Inspector pane by default.

As a result of these exceptions, it is incumbent upon you to provide the features your users expect. In essence, the CompleteReplacement region allows to come really close to replacing the user interface for Outlook items.

How to build a custom Outlook form region?

To create a custom Outlook form region, you first add an ADXOutlookForm to your project. You then design it and add your logic to it. Of course there is a little bit more to it. I’ll walk you through it. I’m going to assume you have Visual Studio open along with an ADX COM Add-in project that targets Outlook.

1. Add an Outlook form. In Visual Studio, click Project > Add New Item. In the Add New Item dialog box, find the Add-in Express Items in the left pane. Select the ADX Outlook Form template and click the Add button.

   Set the following form properties:

   • BackColor = 112,172,71
   • Text = Outlook Form Region
2. Add an Outlook Forms Manager. When you add an ADXOutlookForm to your project, Add-in Express alerts you to the fact that you need to add a special component to manage the form.

   This manager, as I explained earlier, is the ADXOlFormsManager.

   1. So, open the AddinModule in design view.
   2. Right-click in the design surface and select Add Outlook Forms Manager from the context menu.
   3. Alternatively, you can click the Add Outlook Forms Manager button that is available at the top of the AddinModule designer.
3. Add a Form Collection Item. Select the AdxOlFormsManager1 component to display its designer in the bottom of the AddInModule design view. Right-click and click Add.
4. Configure the Form Collection. We want the form to display for mail items in both the Explorer and Inspector windows. Set the following properties:
   1. Inspector Group
      1. InspectorItemTypes = Mail, Task, Calendar
      2. InspectorLayout =BottomSubPane
   2. Misc Group
      1. AlwaysShowHeader = True
      2. CloseButton = True
      3. FormClassName = OutlookForms.ADXOlForm1
      4. UseOfficeThemeForBackground = False

You can leave all other properties as is. I’ll let you explore them on your own. Here is what the form looks like in runtime in Outlook 2013:

By the way, if you want to turn the form into an InspectorRegion or CompleteReplacement region, change the Form Collections InspectorLayout property to InspectorRegion or CompleteReplacement.

It’s that easy.

What else can advanced Outlook form regions do?

Displaying custom forms all over Outlook user interface is compelling enough. But, this is not the only trick they know. They can do several other things.

Display states

Form regions support three states:

• Normal – the default state.
• Minimized – another way to think of it is “collapsed”.
• Hidden – hidden but a splitter is visible to allow for displaying it again.

The best way to understand them is to look at these screenshots:

Minimized form region in Outlook 2013:

Hidden Outlook form region:

Drag-and-drop

In the demo above, we specified the initial location of the Outlook form region as BottomSubPane. You can restrict the form to only reside in the specified pane, or you can allow the user to drag-n-drop the form region to any of the other panes.

To enable this feature, you do the following:

1. Use the same project as the previous demo. Open the AddInModule in design view.
2. Click the AdxOlFormManager1. Open its Items collection.
3. In the ADXOlFormsCollection Editor, click ADXOlFormsCollectionItem1.
4. Set InspectorAllowedDropRegions = BottomSubpane;InspectorRegion;LeftSubpane;RightSubpane;TopSubpane

At runtime, the user can click the Outlook form region’s header, and drag it. When initiate this action, Add-in Express displays a “drop area” icon.

The user can drag the form to the icon that represents their target area and, BOOM, your custom form now resides there.

Persistence

Neither of the previous two features would be useful if not for persistence. With persistence, Add-in Express saves the state of the advanced Outlook form region so that it will display in the same way the next time the user sees it. This means we persist the region’s display state, size & location.

Context binding

Outlook is a productivity app that allows the user to work with mail, tasks, contacts, calendar and more. The bottom line is Outlook displays different UI elements and commands based on the Outlook item type that is “in-context”. Add-in Express supports this context sensitivity via context binding. With context binding, you have complete control and can define what contexts trigger the display of your form region.

The Outlook Forms Manager handles the job of detecting context changes. When one occurs, the form manager scans the collection items found in its Items collection and looks for a match. If it finds a form that matches the current content, it will display the form.

The methods you can use to bind your form to specific context are by configuring the following ADXOlFormsCollectionItem properties…

• InspectorItemTypes :: This is what we did in the demo section. You specify what Outlook folder item types should trigger the display of your custom form.
• FolderName and FolderNames :: Some example folder paths are:
  • \\Personal Folders\Inbox
  • \\Outlook Data File\Inbox
  • \\Outlook Data File\Inbox\SubFolder
    

• InspectorMessageClass and InspectorMessageClasses :: If you have a custom message class or want to use one of the built-in Outlook message classes, define it here. An example could be “IPM.Note.MyMessageClass”.

It bears noting that these features work with Outlook Explorer view regions in addition to Inspector form regions. Also, did I mention these features are out-of-the-box and do not require you to code them?

How to enumerate / access Outlook form regions and controls?

After you know how to build an Outlook form, you’ll want / need to know how to access them in your code. To master this task, you need understand three objects:

• Manager (AddinExpress.OL.ADXOlFormsManager) – Monitors and detects context changes within Outlook. When one occurs, it finds an Outlook form that matches the context and displays it.
• Collection Item (AddinExpress.OL.ADXOlFormsCollectionItem) – This item stores the properties for an Outlook form region. Here, you specify which form to display, where to display (Explorer or Inspector, pane location, etc), what contexts are relevant (Outlook item types, folders, message classes, etc), and how to display it (Show header? Show close button? Show a splitter control?).
• Form (AddinExpress.OL.ADXOlForm) – This is the custom Outlook form region.

Let’s say you have a custom Outlook form that displays in both Explorer and Inspector windows. Let’s say the user has several windows of Outlook open and you want to enumerate through each instance of your form and count them (or something more useful). The code to make it happen is right here:

Private Sub EnumerateFormInstances()
	Dim itm As AddinExpress.OL.ADXOlFormsCollectionItem
	itm = Me.AdxOlFormsCollectionItem1
	Dim iCount As Integer = itm.FormInstanceCount - 1
 
	For i = 0 To iCount
		Dim frm As ADXOlForm1 = itm.FormInstances(i)
		frm.TextBox1.Text = "Hello World :: " & i + 1
	Next
 
End Sub

How to remove an Outlook form

If you decide you do not want the form any longer, you can delete it’s collection from the forms manager. Just right-click and click delete. The form will still exist in your project but it can’t display if it is not defined as the FormClassName of an ADXOlFormsCollectionItem.

Useful events

Forms Manager

ADXBeforeFormInstanceCreate

This event fires before creating a new instance of your custom Outlook form. It’s a great place to check the current context and prevent display of your form.

Private Sub AdxOlFormsManager1_ADXBeforeFormInstanceCreate(sender As Object, _
    args As AddinExpress.OL.BeforeFormInstanceCreateEventArgs) _
    Handles AdxOlFormsManager1.ADXBeforeFormInstanceCreate
 
    Dim isInspectorForm As Boolean = (args.InspectorObj IsNot Nothing)
        If isInspectorForm Then
            Dim currentItem As Object = _
                TryCast(args.InspectorObj, Outlook.Inspector).CurrentItem
            If currentItem IsNot Nothing Then
                Try
                    Dim mailItem As Outlook.MailItem = _
                        TryCast(currentItem, Outlook.MailItem)
                    If mailItem IsNot Nothing Then
                        If mailItem.Importance = Outlook.OlImportance.olImportanceLow Then
                            args.Cancel = True
                        End If
                    End If
                Finally
                    Marshal.ReleaseComObject(currentItem)
                End Try
            End If
    End If
End Sub

Form region events

We support several events. Each is useful in their own way. I’ve highlighted a few here but be sure to review the form events to learn what’s possible.

ADXBeforeFormShow

This event is good place to access your Outlook form and prepare it for display. Here, I access the Inspector that hosts the form, grab it’s mail item, and insert mail subject into form’s textbox control.

Private Sub ADXOlForm1_ADXBeforeFormShow() Handles Me.ADXBeforeFormShow
	Dim ins As Outlook.Inspector
	ins = Me.InspectorObj
	Dim itm As Outlook.MailItem
	If ins IsNot Nothing Then
		'I can make this assumption b/c my form only displays for mail items
		itm = ins.CurrentItem
 
		Me.TextBox1.Text = itm.Subject
 
	End If
End Sub

SelectionChange

This event lets you respond when the user selects a different Outlook item. The following code displays an Outlook form with each change. Although potentially annoying to your users, it ensures they see your form.

Private Sub ADXOlForm1_ADXSelectionChange() Handles Me.ADXSelectionChange
	'Show the form anytime the user navigates to a new mail item
	Me.RegionState = ADXRegionState.Normal
End Sub

Other useful events

The above examples serve to get you started. These also come in handy:

• ADXOlFormsManager.NewInspector :: Whenever a new inspector window opens, the forms manager fires this event.
• ADXOlForm.ADXFolderSwitch :: This event occurs after Outlook’s FolderSwitch event and before the ADXOlForm displays.
• ADXOlForm.BeforeInspectorSubPaneClose :: This is the “before close” event. It executes just before the Outlook form region is disposed of.
• ADXOlForm.InspectorActivate :: Occurs after Outlook’s InspectorActivate event.

How to access form items?

To access Outlook form items, you first need to reference an instance of the form.

Form instance

To get the active form reference, you need to call the collection item’s GetCurrentForm method:

Private Sub GetActiveForm()
    Dim myOlForm As ADXOlForm1
    myOlForm = _
        AdxOlFormsCollectionItem1.GetCurrentForm(AddinExpress.OL.EmbeddedFormStates.Active)
    MsgBox("Text = " & myOlForm.TextBox1.Text)
End Sub

After you have a reference to the form, you can access its controls just as you would with any other Windows forms. For instance, my custom form has a textbox and a combo box.

Text boxes and other form controls

I can update the form’s text box by implementing this code:

Private Sub UpdateActiveFormTextBox(newText As String)
    Dim myOlForm As ADXOlForm1
    myOlForm = _
        AdxOlFormsCollectionItem1.GetCurrentForm(AddinExpress.OL.EmbeddedFormStates.Active)
    myOlForm.TextBox1.Text = newText
End Sub

This strategy works the same for any control on my custom Outlook form. For example, if I want to read the value of combo box on the form, the code is:

Private Function ReadComboBoxValue() As String
    Dim myOlForm As ADXOlForm1
    myOlForm = _
        AdxOlFormsCollectionItem1.GetCurrentForm(AddinExpress.OL.EmbeddedFormStates.Active)
    Return myOlForm.ComboBox1.SelectedText
End Function

ADOlFormsCollectionItem.FormInstances()

This method allows enumerating all instances of your Outlook form region created for the specified ADOlFormsCollectionItem. Use the FormInstanceCount property to get the total number of form instances created for this ADOlFormsCollectionItem.

***

Outlook form regions is a big topic and I encourage you to read our manual covering Advanced Outlook Regions as well as many posts on Outlook regions we have on this blog. Mastering them is essential to building apps your users love.

Outlook 2013 add-in development in Visual Studio 2012 for beginners

• Part 1: Outlook add-in development: Outlook Application and base objects
• Part 2: Creating custom Outlook views
• Part 3: Creating custom Outlook forms
• Part 4: Outlook UI – Explorer and Inspector Windows. What is customizable?
• Part 5: Customizing Outlook main menu, context menus and Backstage view
• Part 6: Creating custom Outlook ribbons and toolbars
• Part 7: Advanced view regions for Outlook 2013 – 2003
• Part 8: Advanced form regions for Outlook 2013 – 2003
• Part 9: Working with Outlook Accounts, Stores, Folders and Items
• Part 10: Working with Outlook calendar
• Part 11: Working with Outlook tasks

You may also be interested in:

• Advanced Outlook view and form regions – basic concepts
• Advanced Outlook form region types