Ty Anderson

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?

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

Outlook form regions mockup

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.

InspectorRegion mockup

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.

Complete Replacement region mockup

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.Adding an Outlook form

    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.Outlook Forms Manager warning

    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:

A custom Outlook form at runtime

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.

Changing the Form Collections InspectorLayout property to 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:

A minimized form region in Outlook 2013

Hidden Outlook form region:

A hidden form region in Outlook 2013

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.

A drop area icon is deisplayed to the end-user

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
      Binding a form region to a certain Outlook folder
  • 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

You may also be interested in:

11 Comments

  • https://secure.gravatar.com/avatar/b8c51812542fc9f59ee946e74bb7db5b?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G syed says:

    Hello ..

    Is it possible to add a drop-down list that will result into further multiple questions, depending on the chosen option ?

    For example if ill add a field “property status” with a selection list of 1. Rent, 2. Sale, 3. Purchase to a form, and I choose “Rent”, it will show further input questions/fields like Rental amount, Tenure, Security Deposit.

    Or If ill chose “Sale”, it will show further fields like Amount of Budget, Available financing ?

    Thanx

  • https://secure.gravatar.com/avatar/c68f03884efb33fd95bcfbd9f1078c07?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Ty Anderson says:

    Hello Syed,

    Yes this all possible. The advanced forms inherit from Windows Forms. Therefore, Windows Controls are available.
    You can respond to your drop down’s change event and repopulate controls or create new ones on the fly.

  • https://secure.gravatar.com/avatar/b8c51812542fc9f59ee946e74bb7db5b?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G syed says:

    Thanx for replying ..I am new to outlook .. can you please guide how is this possible ?

  • https://secure.gravatar.com/avatar/c68f03884efb33fd95bcfbd9f1078c07?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Ty Anderson says:

    Hi Syed

    Are you using Addin Express or VBA? If you can tell us what technology you are utilizing, that will help.

    Nonetheless, you need to learn the basics of Outlook programming. There is a great list of books here:

    http://www.outlookcode.com/article.aspx?id=54

    I recommend starting with the first book listed.

    Also, Microsoft has a page specifically for Outlook developer topics:
    http://msdn.microsoft.com/en-us/office/aa905455.aspx

    But…to answer your question and achieve your goal, it is a simple as this:

    1. Create a form
    2. Add your drop down controls
    3. Add code to the Change event of the drop down control that will act as the filter for the other drop downs. For example:

    Public Sub Parent_Combo_AfterUpdate()

    [update child drop down/combox #1]
    [update child drop down/combox #2]
    [update child drop down/combox #3]

    etc.
    End Sub

    Granted, each of these steps isn’t as simple as it sounds.

    Do I make sense?

  • https://secure.gravatar.com/avatar/cab9762dc96a1fc3e23273d516919ce1?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Raghunathan S says:

    Hi

    We are using the Add-in Express Regions for Microsoft Outlook and VSTO Professional product for creating Forms for the Outlook 2010, 2013 Add-Ins

    Microsoft VS 2010, Windows 7 64bit OS.

    I have a doubt in creating a outlook region.

    Is it possible to create a region like this

    |————————————————|
    | Outlook’s Main Ribbons, Command Bars, Menus |
    |————————————————|
    | | |
    | Folder | ADDIN EXPRESS REGION HERE …. |
    | Navigation | |
    | |———————————-|
    | & | INBOX Search | Outlook’s |
    | |—————- | Message |
    | Other |Drag columns… | Reading Pane |
    | Panes |—————–| |
    | | Outlook | |
    | | Folder’s | |
    | | Mail Items | |
    | | View (List) | |
    | | [SUPERGRID] | |
    | | | |
    |————————————————|

    If it is possible, please explain the step for achieving the same.

    Thanks is Advance.

  • https://secure.gravatar.com/avatar/cab9762dc96a1fc3e23273d516919ce1?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Raghunathan S says:

    Hi

    Sorry about the misaligned text in the previous post..
    All i wanted is the region to be placed horizontally
    above the Mail Items (Supergrid) List View and Reading Pane (Reading pane set to the right side)

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Raghunathan,

    All available region types are listed at http://www.add-in-express.com/docs/net-task-panes.php, see the section Advanced Outlook form and view regions. That is, the only region type that meets your requirement is ExplorerLayout=DockTop.

  • https://secure.gravatar.com/avatar/c1e87431a0b7cc759f833d32dac0a029?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Senthilkumar says:

    Is it possible to design a custom paragraph in new bulk mail(Which is an add in we created using add in express). We want to customize the paragraph which is under format text to include one customized bullet style. Can you please help me with that?

  • https://secure.gravatar.com/avatar/c68f03884efb33fd95bcfbd9f1078c07?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Ty Anderson says:

    Hello Senthil

    I am not familiar with your add-in but I don’t see what this scenario isn’t possible.
    I don’t think i completely follow you however.
    Which version of Outlook?
    Is Outlook utilizing Word as the email editor?
    What style does the formatted text have (the one that the bulleted style will reside under)?

    Ty

  • https://secure.gravatar.com/avatar/8146946cd5e5bcfe059482f8f74a5096?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dev Tek says:

    Thanks for the great post!
    I followed you instructions and encounter a question:

    I would like to create a replace from region, that overrides the contact inspector.
    However, I cannot find the way to create a replacement form region that replaces common inspector such as Outlook contact or task.

    Any ideas?
    Thanks in advance!

  • https://secure.gravatar.com/avatar/ab4ec2858cfdf1e44dadf8c50fae314d?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dmitry Kostochko (Add-in Express Team) says:

    Hi Dev,

    You can try using the CompleteReplacement region type, it overlays everything except for the ribbon. Is this what you are looking for?

Post a comment

Have any questions? Ask us right now!