Controlling Outlook region’s state and form’s size in Add-in Express 2010

Hello folks! This article implies that you are already familiar with the functionality of
Advanced custom task panes and Advanced Outlook form and view regions. If not, you may want to have a look at those pages first.

Here I will tell you how and where you can control the state of the regions where a custom task pane or an Outlook region is located, and also show how you can control the size of those forms.

When I say “a form”, I mean an instance of ADXOlForm, ADXExcelTaskPane, ADXWordTaskPane or ADXPowerPointTaskPane. “A region” means ExplorerLayout or InspectorLayout for Outlook and Position for Excel, Word and PowerPoint.

So, in Add-in Express 2010 we added one more form’s state – RegionState. This state may have one of three values: Normal, Hidden, Minimized. We allow changing the RegionState property for visible forms only and only in particular events of the form. You can also control a region by referring a visible form from a commandbar or by clicking a button on the form.

I will remind that 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.

Well, here is the list of items that I am going to cover in this article:

• Changing the RegionState property from a commandbar or event handler of a control placed on the form
• Changing RegionState in the ADXBeforeFormShow and ADXBeforeTaskPaneShow events
• Changing RegionState in the ADXAfterFormShow and ADXAfterTaskPaneShowevents events
• Changing RegionState in the ADXOlForm.ADXSelectionChange event
• Changing RegionState in the ADXExcelTaskPane. ADXBeforeCellEdit and ADXAfterCellEdit events
• Changing the form’s size
• Some limitations

1. Changing the RegionState property from a commandbar or event handler of a control placed on the form

You can change the region’s state by getting a visible form instance and setting its RegionState property.

private void adxCommandBarButton1_Click(object sender)
        {
            ADXOlForm1 visibleForm = GetVisibleForm() as ADXOlForm1;
            if (visibleForm != null)
            {
                ChangeRegionState(visibleForm);
            }
        }
 
        private AddinExpress.OL.ADXOlForm GetVisibleForm()
        {
            return adxOlFormsCollectionItem1.GetCurrentForm(AddinExpress.OL.EmbeddedFormStates.Visible);
        }
 
        private void ChangeRegionState(AddinExpress.OL.ADXOlForm form)
        {
            if (form == null) return;
 
            switch (form.RegionState)
            {
                case AddinExpress.OL.ADXRegionState.Hidden:
                    form.RegionState = AddinExpress.OL.ADXRegionState.Minimized;
                    break;
                case AddinExpress.OL.ADXRegionState.Minimized:
                    form.RegionState = AddinExpress.OL.ADXRegionState.Normal;
                    break;
                case AddinExpress.OL.ADXRegionState.Normal:
                    form.RegionState = AddinExpress.OL.ADXRegionState.Hidden;
                    break;
            }
        }

If you attempt to set the RegionState property for an invisible form, nothing will happen. When trying to read the property of an invisible form, you will get the value of the state of the region in which the form is supposed to be shown.

You can also manage the region's state of a visible form from the form itself. For example:

private void button1_Click(object sender, EventArgs e)
        {
            this.RegionState = AddinExpress.OL.ADXRegionState.Minimized;
        }

Use the SetFocus Windows API method to return the focus to an Inspector or Explorer window when a region is hidden or minimized.

using System.Runtime.InteropServices;
 
        private void button1_Click(object sender, EventArgs e)
        {
            RegionState = AddinExpress.OL.ADXRegionState.Minimized;
            SetFocus(this.CurrentOutlookWindowHandle);
 
        }
 
        [DllImport("user32.dll")]
        public static extern IntPtr SetFocus(IntPtr hWnd);

2. Changing RegionState in ADXBeforeFormShow and ADXBeforeTaskPaneShow events

In spite of the fact that a form is not visible yet in the ADXBeforeFormShow and ADXBeforeTaskPaneShow events, you can read and set the RegionState property there.

bool _mailContainsInportantInfo = false;
        private bool MailContainsInportantInfo(object Inspector)
        {
            _mailContainsInportantInfo = !_mailContainsInportantInfo;
            return _mailContainsInportantInfo;
        }
 
        private void ADXOlForm1_ADXBeforeFormShow()
        {
            if (MailContainsInportantInfo(this.InspectorObj))
            {
                RegionState = AddinExpress.OL.ADXRegionState.Normal;
            }
            else
            {
                RegionState = AddinExpress.OL.ADXRegionState.Minimized;
            }
        }

BTW, in these events the Visible property is set to True and you can change it in this way preventing the form from being shown. If you set the RegionState property after setting Visible to False, the region’s state will not change. In this case the rule of “not changing RegionState for an invisible form” goes off.

private void ADXOlForm1_ADXBeforeFormShow()
        {
            Visible = false;
            //The next line is useless
            RegionState = AddinExpress.OL.ADXRegionState.Minimized;
        }

3. Changing RegionState in ADXAfterFormShow and ADXAfterTaskPaneShowevents events

In these events you can check the Active property in order to avoid changing the region’s state if another form is active.

private void ADXOlForm1_ADXAfterFormShow()
        {
            if (Active)
            {
                RegionState = AddinExpress.OL.ADXRegionState.Minimized;
            }
        }

Calling the Activate method results in the form being placed on top of all other forms of a given region and the region expands to the Normal state.

private void ADXOlForm1_ADXAfterFormShow()
        {
            if (!Active)
            {
                Activate();
            }
        }

4. Changing RegionState in ADXOlForm.ADXSelectionChange event

In addition, when programming for Outlook, you can change the RegionState property in the ADXOlForm.ADXSelectionChange event:

bool showNormalRegionForSelection = true;
        private void ADXOlForm1_ADXSelectionChange()
        {
            if (showNormalRegionForSelection)
            {
                this.RegionState = AddinExpress.OL.ADXRegionState.Normal;
            }
            else
            {
                this.RegionState = AddinExpress.OL.ADXRegionState.Hidden;
            }
 
            showNormalRegionForSelection = !showNormalRegionForSelection;
        }

5. Changing RegionState in ADXExcelTaskPane. ADXBeforeCellEdit and ADXAfterCellEdit events

When developing against Excel, you can modify the region’s state in the ADXBeforeCellEdit and ADXAfterCellEdit events of the form:

private void ADXExcelTaskPane1_ADXBeforeCellEdit(object sender, AddinExpress.XL.ADXBeforeCellEditEventArgs e)
        {
            this.RegionState = AddinExpress.XL.ADXRegionState.Normal;
        }
 
        private void ADXExcelTaskPane1_ADXAfterCellEdit(object sender, AddinExpress.XL.ADXAfterCellEditEventArgs e)
        {
            this.RegionState = AddinExpress.XL.ADXRegionState.Hidden;
        }

6. Changing the form’s size

In Add-in Express 2010 we have added the ability to resize advanced regions and advanced task panes programmatically if the Splitter property of corresponding items is set to Standard.

You can do this in the ADXAfterFormShow/ADXAfterTaskPaneShow event:

private void ADXOlForm1_ADXAfterFormShow()
        {
            this.Width = 50;
        }

7. Some limitations

When the region is in the minimized state, the user can expand the form by clicking on the form’s button; this opens the form so that it overlays a part of the Outlook window near the form region. There is no way to do this programmatically.

The ADXBeforeFormShow and ADXBeforeTaskPaneShow events do not provide any means to detect if any other form is in the region in order to avert changing the region’s state of the region.

In the Add-in Express events of the form that are unfit for reading or modifying the RegionState property, you will get the following exceptions:

“It is not possible to get the RegionState property at the moment.”
“It is not possible to set the RegionState property at the moment.”

That seems to be all. Please be aware that we do not recommend stepping out of the line when modifying the RegionState property and using methods other than I described above, because it was neither designed nor tested and may produce results that you did not expect.

You may also be interested in:

• Outlook view and form regions: To-Do bar, Preview pane
• Create custom Outlook views and forms