Fedor Shihantsov

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:

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:

10 Comments

  • Andrei says:

    Hi Fedor, very nice presentation! I have tried this scenario:

    I have added this ADXOlForm (that contains a button that can be clicked) in the BottomNavigationPane of Outlook 2010 and when I click it I need to display a custom form in the webViewPane. After that custom form is being displayed in the WebViewPane I want to come back to my Inbox folder and when I click on Inbox the custom form dissapears from the WebPane, but the Inbox folder is not displaying the mail items.
    If click once again on Inbox folder I get the desired behaviour.
    I looked in the code and apparently after I click in my ADXOlForm and then click on Inbox the ExplorerFolderSwitch event is not triggered anymore.
    It is only triggered the second time I click Inbox and I don’t understand why this happens.

    Do you have any clue why that happens?
    Thank you.

    Thanks,
    Andrei

  • Dmitry Kostochko (Add-in Express Team) says:

    Hi Andrei,

    Sorry, I cannot tell you why this happens off the top of my head. Obviously, we need to have a look at your code to pin down the source of the problem. Please contact our support service and our tech guys will do their best to help.

  • Ganesh says:

    I am creating an outlook advanced region via addin express with two forms in its firm collection, say frm1 and frm2. Forms are different. I have two buttons in ribbon, say btn1, and btn2. When btn1 is pressed, I want frm1 to show. User should not be able to switch to frm2 in this state. User will enter info on frm1 and hit ok or cancel. On ok, info will be saved, on cancel info will be ignored. User cannot close or ignore. Ideally frm1 should be modal, but ok if not.

    Same should happen for btn2 and frm2.

    We are seeing that when we hide frm2 frm1 automatically hides and vice a versa. Is there an example similar to my requirement?

    Thanks in advance.

    Ganesh

  • Andrei Smolin (Add-in Express Team) says:

    Hello Ganesh,

    There’s no such example. I believe you describe a modal System.Windows.forms.Form; an ADXOlFrom cannot be shown modally.

  • Kushan says:

    Hi,

    This article helped me to the following issue which I have posted on stackoverflow.
    https://stackoverflow.com/questions/27621238/outlook-forms-collection-item-can-not-be-disabled

    Thanks for Mr.Eugene Astafiev for directing me to this article.

    Cheers!

  • Kushan says:

    “private void ADXOlForm1_ADXAfterFormShow()” I can’t find that event under my adxFormsManager. I am using Add-in Express version 7.5 Release (build 4072). Please advice me. Any help or even hints I would greatly appreciated

  • Kushan says:

    “private void ADXOlForm1_ADXAfterFormShow()” I can’t find that event under my adxFormsManager. I am using Add-in Express version 7.5 Release (build 4072). Please advice me. Any help or even hints would be greatly appreciated.

    Kushan Randima.
    Software Engineer
    Davton Ltd

  • Andrei Smolin (Add-in Express Team) says:

    Hello Kushan,

    That event is declared on the ADXOlForm, not on ADXOlFormsManager.

  • Kushan says:

    I used following code to show/hide a ADX form

    public void HideMe()
    {
    this.RegionState = AddinExpress.OL.ADXRegionState.Hidden;
    }

    public void ShowMe()
    {
    this.RegionState = AddinExpress.OL.ADXRegionState.Normal;
    }

    This hides only the ADX form. The region behind the ADX form will remain. How I hide the form with the region which is associated with that (Completely hide)??

    Thank You
    Kushan Randima.
    Software Engineer
    Davton Ltd

  • Andrei Smolin (Add-in Express Team) says:

    Hello Kushan,

    Use ADXOlForm.Show() and ADXOlForm.Hide() instead. Also, please refer to section Controlling Form Visibility in the manual, see the PDF file in the folder {Add-in Express}\Docs on your development PC.

Post a comment

Have any questions? Ask us right now!