HowTo: Identify the state and location of an Outlook form

Add-in Express 2008 allows placing several forms into one Outlook region or task pane. In addition, Add-in Express 2009 enables the end-user to drag and drop custom forms to wherever they want (naturally, with the developer’s permission). Do you need to know where your form is now and in what state? Of course, you do.

Normally, you may need this, for example, to update data only in visible forms / task panes. So, here goes! In our sample add-in, we are going to embed custom forms into the Outlook Explorer and Outlook Inspector windows, two forms into each. In this example, we need to know which of the window types, explorer or inspector, a given form belongs to and somehow identify this form, say, by its caption. All this can be done in the ADXBeforeShow event handler:

Private isExplorer As Boolean = False
 
Private Sub ADXOlForm1_ADXBeforeFormShow() _
    Handles MyBase.ADXBeforeFormShow
 
    If Me.Text = "ADXOlForm1" Then
        If Me.ExplorerObj IsNot Nothing Then
            Me.isExplorer = True
            Me.Text = "Explorer Form " + _
             (Me.Item.Collection.IndexOf(Me.Item) - 1).ToString()
        End If
        If Me.InspectorObj IsNot Nothing Then
            Me.isExplorer = False
            Me.Text = "Inspector Form " + _
             (Me.Item.Collection.IndexOf(Me.Item) + 1).ToString()
        End If
    End If
End Sub

We can identify the Outlook region in which your form appears at this very moment using the following code:

Public Function GetFormRegion(ByVal Instance As ADXOlForm) As Object
    If DirectCast(Instance, ADXOlForm1).isExplorer Then
        Return Instance.Item.ExplorerLayout
    End If
    Return Instance.Item.InspectorLayout
End Function

The next question is the form state. To identify the state, I suggest using the following type:

Public Enum FormState
    Focused
    Visible
    InRegion
    InCache
End Enum

And here’s what the terms above mean:

• Focused – Outlook form is visible, active, the focus is on the form.
• Visible – Outlook form is visible.
• InRegion – Outlook form is in the region, but is not visible. It may, e.g. be overlaid with another form, or be in the Minimized or Hidden state.
• InCache – Outlook form is in Cache. A form instance is created by default for each Outlook folder which was opened.

The code below will return us the form state:

Public Function GetFormState(ByVal Instance As ADXOlForm) As FormState
    If Instance.Visible AndAlso _
        Instance.Active AndAlso _
        CheckFocused(Instance) Then
        Return FormState.Focused
    End If
    If Instance.Visible AndAlso Instance.Active Then
        Return FormState.Visible
    End If
    If Instance.Visible Then
        Return FormState.InRegion
    End If
    Return FormState.InCache
End Function
 
Public Function CheckFocused(ByVal Instance As ADXOlForm) As Boolean
    For I As Integer = 0 To Instance.Controls.Count - 1
        If Instance.Controls(I).Focused Then
            Return True
        End If
    Next I
    Return False
End Function

Now we need to iterate the ADXOlFormsManager.Items collection, get all form instances by using the FormInstances method, then get the form state and the region in which the form is located, and output the result:

Private Sub ButtonCheckForms_Click(ByVal sender As _
    System.Object, ByVal e As System.EventArgs) _
    Handles ButtonCheckForms.Click
 
    Dim text As String = String.Empty
    Dim I, J As Integer
    For I = 0 To Me.FormsManager.Items.Count - 1
        For J = 0 To Me.FormsManager.Items(I).FormInstanceCount - 1
            Dim form As ADXOlForm = _
                Me.FormsManager.Items(I).FormInstances(J)
            If form IsNot Nothing AndAlso form IsNot Me Then
                text = text + _
                    form.Text + Environment.NewLine + _
                    "State: " + GetFormState(form).ToString() + _
                    Environment.NewLine + _
                    "Region: " + GetFormRegion(form).ToString() + _
                    Environment.NewLine + Environment.NewLine
                DirectCast(form, ADXOlForm1).TextBoxDetails.Clear()
            End If
        Next J
    Next I
 
    TextBoxDetails.Text = _
        "--- THIS FORM: ---" + Environment.NewLine + _
        Me.Text + Environment.NewLine + _
        "State: " + GetFormState(Me).ToString() + _
        Environment.NewLine + _
        "Region: " + GetFormRegion(Me).ToString() + _
        Environment.NewLine + Environment.NewLine + _
        "--- OTHER FORMS: ---" + Environment.NewLine + _
        text
End Sub

If you have any questions or comments, you are most welcome!

For more information about Advanced Outlook Regions see:
Complete review: Advanced Outlook Regions basics
Complete review: Outlook Explorer and Inspector regions
Complete review: Outlook Regions – cached instancing, exposing events, read and compose

Available downloads:

Note! The samples below are built using generation 2009 of Add-in Express.

C# sample Outlook add-in for VS 2005
VB.NET sample Outlook add-in for VS 2005