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
Note! The samples below are built using generation 2009 of Add-in Express.