Office Development with Visual Studio : Norm Estabrook

Do Your Outlook UI Elements Need Counseling? - Get your Form Regions, Ribbons, and Task Panes Talking to Each Other Again (Norm Estabrook)

VSTO Team — Thu, 04 Jun 2009 01:30:31 GMT

So you want to open a task pane by using a button on the Ribbon. You also want a form region that appears in an e-mail item to detect the state of a control on a custom task pane so that you can add or remove an option that appears in a Ribbon menu right? Ok, I completely made this scenario up. But at some point, somewhere along the way, you might say to yourself – how do I get to that gallery on my Ribbon from my task pane? or how do I enable the user to populate that combo box on the form region by selecting a control on the Ribbon? Well if that describes something that you are trying to do, then this post is for you. Let’s start with Ribbons. The other two (form regions and task panes) are bit more troublesome.

Ribbons

Ribbon controls are the easiest to access from other areas of your application. Assuming that your custom Ribbon is named Ribbon1, here is what you do:

ThisRibbonCollection ribbonCollection =
Globals.Ribbons
[Globals.ThisAddIn.Application.ActiveInspector()];
ribbonCollection.Ribbon1.comboBox1.Text = "Hello World";

You can read more about this here.

Form Regions

For the VB folks, this is a snap. C# developers have to do a bit more work. That is because by default, in a C# project, the controls that you add to a form region are private. For each control that you want to access, you have to set the Modifiers property of the control to Internal or Public. For example:

You can then add code to access the control. For example, assuming that your form region is named FormRegion1, you could use the following code:

WindowFormRegionCollection formRegions =
    Globals.FormRegions
        [Globals.ThisAddIn.Application.ActiveInspector()];
formRegions.FormRegion1.textBox1.Text = "Hello World";

You can read more about this here.

Custom Task Panes

Controls on task panes require the same tweaks described for form regions above. Here is an example of how to get to a button on a task pane. This example makes the following assumptions:

The user control of the custom task pane is named MyUserControl.
The task pane is named myCustomTaskPane and it is declared as public in your code.

((MyUserControl)Globals.ThisAddIn.myCustomTaskPane.Control).button1.Text = "It Worked";

If have not yet created a custom task pane, see this topic and it will all make sense.

As a side note, if you are adding custom task panes to Outlook Inspector windows, you have to write a bit of code to map each Inspector window with it’s own instance of a custom task pane. If you don’t do this mapping, you get all kinds of wacky issues. For an example of how to do this, see the following article.

For the sake of being thorough, here is an example of how you can access a task pane created by using the guidance in that article.

private void toggleButton1_Click(object sender, RibbonControlEventArgs e)
{
    Outlook.Inspector inspector = (Outlook.Inspector)e.Control.Context;
    InspectorWrapper inspectorWrapper = Globals.ThisAddIn.InspectorWrappers[inspector];
    CustomTaskPane taskPane = inspectorWrapper.CustomTaskPane;
    if (taskPane != null)
    {
        taskPane.Visible = ((RibbonToggleButton)sender).Checked;
        taskPane.DockPosition = Microsoft.Office.Core.MsoCTPDockPosition.msoCTPDockPositionBottom;
        taskPane.Height = 475;
    }
}

Hope this helps!

Norm E.

Here is a Way to Get the ID of a Built-in Outlook Command Bar Menu (Norm Estabrook)

VSTO Team — Fri, 01 May 2009 00:09:27 GMT

Recently, a forum poster asked us how he could add a submenu item to a built-in menu item in Outlook. Note that these are not controls that appear on the Ribbon of an Outlook item, but rather the menus that drop down from the top of the Outlook Explorer such as the View menu and the Tools menu.

So one way to do this (In fact the only way that I know of) is to use the example shown in the following MSDN topic - How to: Add Custom Menus and Menu Items to Outlook.

You can’t just use the example as is. You will need to add a line of code to get a handle to a built-in menu. The following example gets a handle to the Junk E-Mail menu that appears off of the Actions menu of the Outlook Explorer window.

Office.CommandBarPopup junkEmailMenu = (Office.CommandBarPopup)
this.Application.ActiveExplorer().CommandBars.FindControl
(Office.MsoControlType.msoControlPopup, 31353, missing, missing);

Note the ID number shown in the second parameter to the FindControl method. How on earth did I know that the Junk E-Mail menu is the 31353 menu? The answer is … Not very easily. In fact to obtain that ID, I wrote a small Outlook add-in that iterates through all menus in Outlook and prints out their corresponding codes. I figured that I would share this with you in case you ever have a similar scenario.

Two notes about the sample below: First - this is a C# example, so my apologies to VB’ers. Second - this example is meant to be used in a Visual Studio 2008 Outlook (2007 or 2003) add-in project. These projects automatically include the appropriate using statements that enable you to use the prefix “Office” in place of “Microsoft.Office.Core” when referring to some objects etc.

Ok. Here is the code:

public partial class ThisAddIn
{
    private void ThisAddIn_Startup(object sender, System.EventArgs e)
    {
        Outlook.Application app = this.Application;
        //Create a new txt file to record controls' list

        System.IO.StreamWriter sw = System.IO.File.CreateText
            (@"C:\Outlook Menus.txt");

        //loop through Outlook ActiveExplorer CommandBars to get all CommandBars

        foreach (Office.CommandBarControl cb in app.ActiveExplorer().CommandBars.ActiveMenuBar.Controls)
        {
            PrintMenuItems(cb, sw);
        }

        sw.Close();

    }

    // Recursive method for printing menus and nested menus.
    // Either the menu is a commandbarpopup (contains submenus)
    // Or it is a commandbarbutton (contains no submenus)

    private void PrintMenuItems(object menuItem, System.IO.StreamWriter sw)
    {
        if (menuItem as Office.CommandBarButton == null)
        {
            // This is a menu bar popup control.
            sw.WriteLine((menuItem as Office.CommandBarPopup).Caption +
                "\t" + (menuItem as Office.CommandBarPopup).Id.ToString());

            if ((menuItem as Office.CommandBarPopup).accChildCount > 0)
            {
                for (int j = 1; j <= (menuItem as Office.CommandBarPopup).accChildCount; j++)
                {
                    PrintMenuItems((menuItem as Office.CommandBarPopup).get_accChild(j), sw);
                }
            }
        }
        else
        {
            // Must be a command
            sw.WriteLine("\t" + (menuItem as Office.CommandBarControl).Caption +
                "\t" + (menuItem as Office.CommandBarControl).Id.ToString());
        }

    }

Enjoy!

Norm E.

Clearing Off Custom Menu Items in Word (Norm Estabrook)

VSTO Team — Tue, 14 Apr 2009 21:37:15 GMT

Last month I posted this article that described how to prevent your add-in from creating duplicate menu items in Word. If you have been experimenting with customization contexts, you might have several menu items that appear when you right click a document. The article that I posted shows how to prevent this from happening for your users, but what about removing the items that appear in your instance of Word – the one that you use for testing?

To clear those off, just add a bit of code to the startup event handler of any old Word add-in. Set the customization context to each possible culprit (template, document, attached template etc.) and then call the Reset method. Be sure to save the template or document after words.

Note - I wouldn’t recommend that you put this code into an add-in that you send out to users as this code will remove all customizations in each context (Even ones that your add-in has not created!). However, it is a cool way to clear up left over menu items from the instance of Word that you use for testing.

private void ResetShortcutMenu()
{
    myApplication.CustomizationContext = myApplication.ActiveDocument;

    myApplication.CommandBars["Text"].Reset();
    myApplication.ActiveDocument.Save();

    myApplication.CustomizationContext = myApplication.ActiveDocument.get_AttachedTemplate();

    myApplication.CommandBars["Text"].Reset();
    ((Word.Template)myApplication.ActiveDocument.get_AttachedTemplate()).Save();

    myApplication.CustomizationContext = customTemplate;

    myApplication.CommandBars["Text"].Reset();
    customTemplate.Save();

    myApplication.CustomizationContext = myApplication.NormalTemplate;

    myApplication.CommandBars["Text"].Reset();
    myApplication.NormalTemplate.Save();
}

My Word Add-In Creates Duplicate Menu Items. Make it Stop! (Norm Estabrook)

VSTO Team — Fri, 06 Mar 2009 20:33:19 GMT

So I want my add-in to place a custom command into the shortcut menu. The shortcut menu is that cool menu that appears when you right-click a document. Great, so I read some articles in MSDN, write some code, run the add-in and voila there it is! I give it to my buddy, he is proud of my accomplishment and and installs my add-in. Now he hates me because every time he opens up Word, a duplicate menu appears. Where did I go wrong?

Well actually, I didn’t do anything wrong. It’s just that Word requires a little more attention when it comes to handling menus. I guess you can say that Word is a bit more “needy” than other Office applications. But being “higher maintenance” does not have to mean “higher maintenance costs”. Hopefully this post will get your friend talking to you again.

My code

Here is the code that did not work for me. BTW – I will paste in both Visual Basic and C# examples for this post.

[Visual Basic]

Private MyApplication As Word.Application
Private WithEvents myControl As Office.CommandBarButton

Private Sub ThisAddIn_Startup _
(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup

    MyApplication = Me.Application
    AddMenuItem()

End Sub

Private Sub AddMenuItem()

    Dim menuItem As Office.MsoControlType = _
        Office.MsoControlType.msoControlButton

    myControl = CType(MyApplication.CommandBars("Text").Controls.Add _
       (menuItem, 1, True), Office.CommandBarButton)

    myControl.Style = Office.MsoButtonStyle.msoButtonCaption
    myControl.Caption = "My Menu Item"
    myControl.Tag = "MyMenuItem"

End Sub


Sub myControl_Click(ByVal Ctrl As Microsoft.Office.Core.CommandBarButton, _
                    ByRef CancelDefault As Boolean) Handles myControl.Click

    System.Windows.Forms.MessageBox.Show("My Menu Item clicked")

End Sub

[C#]

private Word.Application myApplication;
private Office.CommandBarButton myControl;

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    myApplication = this.Application;
    AddMenuItem(); 
}
 
private void AddMenuItem()
{
   Office.MsoControlType menuItem = 
        Office.MsoControlType.msoControlButton;

    myControl = 
        (Office.CommandBarButton)myApplication.CommandBars["Text"].Controls.Add
        (menuItem,missing, missing, 1, true);

    myControl.Style = Office.MsoButtonStyle.msoButtonCaption;
    myControl.Caption = "My Menu Item";
    myControl.Tag = "MyMenuItem";

    myControl.Click += 
        new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler
            (myControl_Click);

}

void myControl_Click(Microsoft.Office.Core.CommandBarButton Ctrl, 
    ref bool CancelDefault)
{
    System.Windows.Forms.MessageBox.Show("My Menu Item clicked");
}

Why my code does not work as expected

Here is one issue I can see right off the bat. Note this line of code for adding a control:

myControl = CType(MyApplication.CommandBars("Text").Controls.Add _ (menuItem, 1, True), Office.CommandBarButton)

I set the last parameter of the Add method to True. This value specifies that I want my control to be temporary. I am trying to tell Word not to save the control so that duplicate menu items won’t be added every time Word opens. Only there is a problem here. Word ignores this parameter (at least for controls in a CommandBar collection anyway). So I can keep it set to true, but it really means false. Lovely.

So what is happening? Well, Word is actually saving your new menu command to the Normal.dot template every time a new instance of Word opens – hence the duplicates.

What can I do about this?

There are probably a billion creative ways to stop the duplicate menus from appearing, but here are three tips that work really well. Here they are:

Check for duplicates before adding an item (control) to a menu.
Always set the customization context of the application to the same document or template before adding or deleting a control.
Because there are no temporary commands in Word, use a custom template to save the commands.

Tip # 1: Check for Duplicates:

This one is pretty easy. Just add code to your add-in that looks for a control that has the same tag as the control you are about to add. If one exists, perform one of the following actions:

Don’t add the control (It is already there).
Delete the control. Then you can add it.

I modified my code to delete the control. Here is my code.

[Visual Basic]

Private Sub RemoveExistingMenuItem()

    Dim contextMenu As Office.CommandBar = _
    MyApplication.CommandBars("Text")

    MyApplication.CustomizationContext = customTemplate

    Dim control As Office.CommandBarButton = contextMenu.FindControl _
        (Office.MsoControlType.msoControlButton, System.Type.Missing, _
         "MyMenuItem", True, True)

    If Not (control Is Nothing) Then
        control.Delete(True)
    End If

End Sub

[C#]

private void RemoveExistingMenuItem()
{
    Office.CommandBar contextMenu = myApplication.CommandBars["Text"];
    myApplication.CustomizationContext = customTemplate;

    Office.CommandBarButton control = 
        (Office.CommandBarButton)contextMenu.FindControl
        (Office.MsoControlType.msoControlButton, missing,
        "MyMenuItem", true, true);

    if ((control != null))
    {
        control.Delete(true);
    }

}

Tip #2: Set the Customization Context

The customization context of the application tells Word where to save your customizations. To specify the customization context, set the CustomizationContext property of the Application object.

By default, Word uses the Normal.dot template as it’s customization context. This is not reliable and can change. If you do not explicitly set the context, you might search for controls saved to one context such as a document, delete controls from another context such as a custom template and then add the control to another context such as Normal.dot.

To avoid these issues, always set the customization context of the application to the same document or template every time you search for, delete, or add controls to a menu.

Note that in a Word document-level customization, it is probably best to set the customization context to the active document. That way when the user uninstalls the customization, the document and the menu commands that pertain to that document disappear as expected.

In Word application-level add-in, the best practice is to use a custom template for reasons mentioned later on in this post.

In the following example, I highlighted in bold the line that sets the customization context. Further along in this post, I will show you where I got customTemplate.

[Visual Basic]

Private Sub AddMenuItem()

    MyApplication.CustomizationContext = customTemplate

    Dim menuItem As Office.MsoControlType = _
        Office.MsoControlType.msoControlButton

    myControl = CType(MyApplication.CommandBars("Text").Controls.Add _
       (menuItem, 1, True), Office.CommandBarButton)

    myControl.Style = Office.MsoButtonStyle.msoButtonCaption
    myControl.Caption = "My Menu Item"
    myControl.Tag = "MyMenuItem"
    customTemplate.Saved = True

    GC.Collect()

End Sub

[C#]

private void AddMenuItem()
{
    myApplication.CustomizationContext = customTemplate;
    Office.MsoControlType menuItem = 
        Office.MsoControlType.msoControlButton;

    myControl = 
        (Office.CommandBarButton)myApplication.CommandBars["Text"].Controls.Add
        (menuItem,missing, missing, 1, true);

    myControl.Style = Office.MsoButtonStyle.msoButtonCaption;
    myControl.Caption = "My Menu Item";
    myControl.Tag = "MyMenuItem";

    myControl.Click += 
        new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler
            (myControl_Click);

    customTemplate.Saved = true;

    GC.Collect();

Also – a quick tip – set the Saved property of the template to true after you add the control. This stops that annoying prompt from appearing that asks if you would like to save your customizations to the template.

Tip #3: Use a Custom Template

It is very difficult to delete a control before the add-in shuts down. For example, if you attempt to delete a control in the ThisAddIn_Shutdown event handler, you will receive a not so helpful COM exception. You will get similar results in the Quit event of Word.

That is because the template that you are using as your application’s customization context is not writable in either of those event handlers. So if you cannot easily delete the control when Word closes, that means that the control will always live inside of the template.

This is a problem if you are using Normal.dot to persist the controls. Here is why. Let’s say the user decides that he does not want to see your command in a menu anymore. With a caption such as “My Menu Item”, can you really blame him? So the user uninstalls your add-in. However, the menu command still lives in Normal.dot! When that user opens his document in Word, "My Menu Item” still appears. Doooh! Here comes the support calls!

The way around this is to provide your own custom template to store customizations such as custom menus and menu items. Your setup application can remove the template along with add-in. That way when the user uninstalls the add-in, they also remove the template that contains the menu items.

In the following example, I retrieve a custom template from the users documents folder. Yes, your setup application will probably use a different location to place the custom template, but this is just for an example.

[Visual Basic]

Private Sub GetCustomTemplate()

    Dim TemplatePath As String = Environment.GetFolderPath _
        (Environment.SpecialFolder.MyDocuments) + "\MyCustomTemplate.dotx"
    Dim install As Boolean = True

    For Each installedTemplate As Word.Template In MyApplication.Templates
        If installedTemplate.FullName = DirectCast(TemplatePath, String) Then
            install = False
        End If
    Next

    If install = True Then
        MyApplication.AddIns.Add(TemplatePath.ToString(), True)
    End If

    customTemplate = MyApplication.Templates(TemplatePath)

End Sub

[C#]

private void GetCustomTemplate()
{
    object TemplatePath = Environment.GetFolderPath
        (Environment.SpecialFolder.MyDocuments) +
        "\\MyCustomTemplate.dotx";
    object install = true;

    foreach (Word.Template installedTemplate in myApplication.Templates)
    {
        if (installedTemplate.FullName == (string)TemplatePath)
        {
            install = false;
        }
    }
    if ((bool)install)
    {
        myApplication.AddIns.Add(TemplatePath.ToString(), ref install);
    }
    customTemplate = myApplication.Templates.get_Item(ref TemplatePath);

}

Drum roll please .. I present the complete example

To provide context, here is the complete sample:

[Visual Basic]

Public Class ThisAddIn

    Private MyApplication As Word.Application
    Private WithEvents myControl As Office.CommandBarButton
    Private customTemplate As Word.Template

    Private Sub ThisAddIn_Startup _
    (ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup

        MyApplication = Me.Application

        GetCustomTemplate()
        RemoveExistingMenuItem()
        AddMenuItem()

    End Sub

    Private Sub GetCustomTemplate()
        Dim TemplatePath As String = Environment.GetFolderPath _
            (Environment.SpecialFolder.MyDocuments) + "\MyCustomTemplate.dotx"
        Dim install As Boolean = True

        For Each installedTemplate As Word.Template In MyApplication.Templates
            If installedTemplate.FullName = DirectCast(TemplatePath, String) Then
                install = False
            End If
        Next

        If install = True Then
            MyApplication.AddIns.Add(TemplatePath.ToString(), True)
        End If

        customTemplate = MyApplication.Templates(TemplatePath)

    End Sub

    Private Sub RemoveExistingMenuItem()

        Dim contextMenu As Office.CommandBar = _
        MyApplication.CommandBars("Text")

        MyApplication.CustomizationContext = customTemplate

        Dim control As Office.CommandBarButton = contextMenu.FindControl _
            (Office.MsoControlType.msoControlButton, System.Type.Missing, _
             "MyMenuItem", True, True)

        If Not (control Is Nothing) Then
            control.Delete(True)
        End If

    End Sub


    Private Sub AddMenuItem()

        MyApplication.CustomizationContext = customTemplate

        Dim menuItem As Office.MsoControlType = _
            Office.MsoControlType.msoControlButton

        myControl = CType(MyApplication.CommandBars("Text").Controls.Add _
           (menuItem, 1, True), Office.CommandBarButton)

        myControl.Style = Office.MsoButtonStyle.msoButtonCaption
        myControl.Caption = "My Menu Item"
        myControl.Tag = "MyMenuItem"
        customTemplate.Saved = True

        GC.Collect()

    End Sub

    Sub myControl_Click(ByVal Ctrl As Microsoft.Office.Core.CommandBarButton, _
                        ByRef CancelDefault As Boolean) Handles myControl.Click

        System.Windows.Forms.MessageBox.Show("My Menu Item clicked")

    End Sub

    Private Sub ThisAddIn_Shutdown() Handles Me.Shutdown

    End Sub

End Class

[C#]

public partial class ThisAddIn
{
    private Word.Application myApplication;
    private Office.CommandBarButton myControl;
    private Word.Template customTemplate;

    private void ThisAddIn_Startup(object sender, System.EventArgs e)
    {
        myApplication = this.Application;

        GetCustomTemplate();
        RemoveExistingMenuItem();
        AddMenuItem();
    }

    private void GetCustomTemplate()
    {
        object TemplatePath = Environment.GetFolderPath
            (Environment.SpecialFolder.MyDocuments) +
            "\\MyCustomTemplate.dotx";
        object install = true;
        foreach (Word.Template installedTemplate in myApplication.Templates)
        {
            if (installedTemplate.FullName == (string)TemplatePath)
            {
                install = false;
            }
        }
        if ((bool)install)
        {
            myApplication.AddIns.Add(TemplatePath.ToString(), ref install);
        }
        customTemplate = myApplication.Templates.get_Item(ref TemplatePath);

    }

    private void RemoveExistingMenuItem()
    {
        Office.CommandBar contextMenu = myApplication.CommandBars["Text"];
        myApplication.CustomizationContext = customTemplate;

        Office.CommandBarButton control =
            (Office.CommandBarButton)contextMenu.FindControl
            (Office.MsoControlType.msoControlButton, missing,
            "MyMenuItem", true, true);

        if ((control != null))
        {
            control.Delete(true);
        }

    }

    private void AddMenuItem()
    {
        myApplication.CustomizationContext = customTemplate;
        Office.MsoControlType menuItem =
            Office.MsoControlType.msoControlButton;

        myControl =
            (Office.CommandBarButton)myApplication.CommandBars["Text"].Controls.Add
            (menuItem, missing, missing, 1, true);

        myControl.Style = Office.MsoButtonStyle.msoButtonCaption;
        myControl.Caption = "My Menu Item";
        myControl.Tag = "MyMenuItem";

        myControl.Click +=
            new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler
                (myControl_Click);

        customTemplate.Saved = true;

        GC.Collect();

    }

    void myControl_Click(Microsoft.Office.Core.CommandBarButton Ctrl,
        ref bool CancelDefault)
    {
        System.Windows.Forms.MessageBox.Show("My Menu Item clicked");
    }
    private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
    {
    }
}

Now you can issue a patch to your buddy so that he has only one “My Menu Item” appearing in his shortcut menu. Although .. I am not sure what “My Menu Item” is really suppose to do …

Making a Custom Ribbon Appear Only for a Custom Outlook Form (Norm Estabrook)

VSTO Team — Wed, 28 Jan 2009 23:09:46 GMT

Many of you have posted questions to the VSTO Forum about how to make custom tabs, groups and controls appear only in cases where the user opens a custom form in Outlook.

The reason why that is difficult to accomplish is because there is no way to specify the names of custom forms in the Ribbon Designer. You can only specify inspector window types.

So if I set the RibbonType property of the Ribbon to “Microsoft.Outlook.Mail.Compose”, then the Ribbon controls appear for all new mail items including items that I create by using a custom mail form. So how can I make sure that the Ribbon controls only appear in my custom mail form?

One possible workaround is to show and hide controls based on the message class of an Outlook form. It seemed to work for me and here is how I did it.

In the Ribbon designer, set the Visible property of your custom controls to false. At this point, those controls will not appear in any Outlook form custom or otherwise.

Next, add a property to the ThisAddIn class that stores the name of a custom message class as follows:

private string strMessageClass = "";
public string MessageClass
{
    get
    {
        return strMessageClass;
    }
    set
    {
        strMessageClass = value;
    }
}

Create an event handler for the NewInspector event. This event is raised every time a new Outlook inspector is open. The item that opens in the inspector has a message class name. For example, if you open a standard mail item, the message class name of the item is “IPM.Note”. A custom form based on a standard email form might have the message class name “IPM.Note.MyCustomForm”.

In the event handler, set your custom string property to the message class name of the open item. Here is an example:

private Outlook.Inspectors inspectors;
private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    inspectors = this.Application.Inspectors;
    inspectors.NewInspector +=
        new Microsoft.Office.Interop.Outlook.InspectorsEvents_NewInspectorEventHandler
            (Inspectors_NewInspector);

}

void Inspectors_NewInspector(Microsoft.Office.Interop.Outlook.Inspector Inspector)
{
    Outlook.MailItem tmpMailItem = (Outlook.MailItem)Inspector.CurrentItem;
    if (tmpMailItem != null)
        MessageClass = tmpMailItem.MessageClass;
}

In the load event of your Ribbon class, check your custom string property to determine the message class of the item that is attempting to load your custom Ribbon. If the name matches the name of your custom message class, you can show the controls on your custom Ribbon. Here is an example:

private void Ribbon1_Load(object sender, RibbonUIEventArgs e)
{
    if (Globals.ThisAddIn.MessageClass == "IPM.Note.Norm")
    {
        group1.Visible = true;
        Globals.ThisAddIn.MessageClass = "";
    }
    

}

Setting the Width of a Drop Down, Combo Box, or Edit Box in the Ribbon Designer (Norm Estabrook)

VSTO Team — Fri, 19 Dec 2008 21:56:00 GMT

Recently, a developer posted a question to the VSTO forum asking us how to set the width of a drop down control by using the Ribbon Designer (http://social.msdn.microsoft.com/Forums/en-US/vsto/thread/8965ae5a-9c02-4aec-9178-675650b7044e/).

As this person experienced, if you do not set the width of the control, the text that appears in a drop down, combo box, or edit box will truncate. For example, the string “I love Visual Studio Tools for Office!” is truncated in the following drop down:

So how do you fix this? The magic lies in the SizeString property. However, the use of this property is not so obvious. Instead of setting this property to a number such as 20 for 20 characters of space, you must type an actual character for each character’s worth of space you want to allocate for the text width.

For example, to make enough space for the string “I love Visual Studio Tools for Office!”, set the SizeString property of the drop down to “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx” or “jlkjlkjlkjlkjdlslaledfoplklksjjklsfdf” etc.

You can also decrease the size of the text area to show fewer characters than appear by default. For example, just set SizeString to “xx” if you want only two characters to appear.

Norm E.

I Just Want to Format a Cell in My Excel Worksheet (Norm Estabrook)

VSTO Team — Tue, 03 Jun 2008 20:41:08 GMT

So you just want to write some code to format a cell in a worksheet. However, there isn't a help topic in sight that shows you how to do it. There may be a topic out there, but you don't have time to sift through the web searching for it. You're not alone. The forums are filled with questions about how to accomplish what might seem like a simple task - like formatting a cell. But the search for the right class, method or property to do it is not so simple.

A great way to get unstuck on some of these small but distracting issues is to use the Excel macro recorder. Start the recorder, pick a cell, format the cell, stop the recorder and then look at the code that Excel generates. The trickiest part is translating the VBA code to C# or VB so that you can use the code in your VSTO project. However, doing this can be a lot easier than searching the web and MSDN for a topic that shows you which specific class or property in the massive Excel object model you need to perform your task.

Let's take a look at an example scenario. All I want to do is format a cell as a percentage with 2 decimal places on the right side. The Macro recorder will show me which method or property I need to use.

To use the Macro recorder in Excel 2007, you have to enable the developer tab in the Ribbon. Click the round Office button and then click "Excel Options". Then select the "Show Developer tab in the Ribbon" as follows.

Start the macro recorder as follows:

Select a cell and then set your formatting options as follows:

Stop the macro recorder. Open the macro in the VBA editor as follows:

Grab the generated VBA. For example the VBA generated by the macro that I recorded looks like this:

Range("B2").Select
Selection.NumberFormat = "0.00%"

Ok this is good. Basically the code is selecting cell B2 and then setting the "NumberFormat" property of the selected range to a percentage with 2 right-side decimal positions. I just need to open my VSTO project and add code that gets the range for cell B2, and then sets NumberFormat property of that range to "0.00%" as follows:

[C#]

Excel.Range range1 = this.Range["B2", missing];
range1.NumberFormat = "0.00%";

[VB]

Dim range1 As Excel.Range = Me.Range("B2")
range1.NumberFormat = "0.00%"

This assumes that you add this code to a sheet class in a document-level customization project. If you are using an application-level add-in project, you might use something like the following which formats the cell "B2" in the default sheet of the workbook.

[C#]

Excel.Range range1 = this.Application.get_Range("B2", missing);
range1.NumberFormat = "0.00%";

[VB]

Dim range1 As Excel.Range = Application.Range("B2")
range1.NumberFormat = "0.00%"

I might have found a topic that shows me how to format a cell as a percentage, but sometimes using the macro recorder can be a lot faster. Especially if the task you want to perform is something that can be done by using common Excel features.

You can still search for answers in the docs. The topic Excel Object Model Overview is a great place to start. There is a section in that topic named "Using the Excel Object Model Documentation" that lists several resources.

Norm E.

Making a Custom Group Appear in the Message Tab of a Mail Item (Norm Estabrook)

VSTO Team — Wed, 09 Apr 2008 19:49:00 GMT

You can add a custom group to the Message tab of an Outlook mail item. For example, here is a custom group named "MyCoolGroup" that I added to the message tab of a new message:

Outlook lets you open a message in the following two modes:

Compose (you are drafting a new message).
Read (you are reading a message).

Making a custom group appear for only one of these modes is pretty easy. Making it appear for both modes is a tad more challenging. That is because the control ID of the Message tab in read mode is different than the control ID of the Message tab in compose mode. When you design your custom group in the VSTO Ribbon designer, you can only specify one control ID. This means that when you run the project, the custom group will only appear in the Message tab of a compose window or the Message tab of a read window depending on which control ID you specify at design-time.

If you want the group to appear in both versions of the Message tab (read and compose), you have to do a bit more work. Here is how you make the group appear for both modes:

First, add a Ribbon (Visual Designer) to an Outlook 2007 add-in project.

Then, set the RibbonType property of the Ribbon to Microsoft.Outlook.Mail.Compose and Microsoft.Outlook.Mail.Read as follows:

On the Ribbon designer, add a group to a tab and customize the group as desired.

On the Ribbon designer, select the tab, open the Properties window, and then set the OfficeId of the tab to TabReadMessage. TabReadMessage is the control ID of the default tab that appears on the Ribbon of a mail message that is open in read mode.

Ok. Now when you run the project, your custom group will appear only if you open a mail item in read mode. Now you need to add a little code to display the custom group in the Message tab of a new mail item. That is, a mail item that you open in compose mode.

To do this, create an event handler for the NewInspector event. This event is raised every time a new Outlook inspector is open. In the event handler, check the EntryID property of the mail item. If this property is null, then the item is a new message. If that is the case, set the OfficeId property of the tab to TabNewMailMessage. TabNewMailMessage is the control ID of the Message tab of a mail message in compose mode.

private Outlook.Inspectors inspectors;
private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    inspectors = this.Application.Inspectors;
    inspectors.NewInspector += 
        new Microsoft.Office.Interop.Outlook.InspectorsEvents_NewInspectorEventHandler
            (Inspectors_NewInspector);
}

void Inspectors_NewInspector(Microsoft.Office.Interop.Outlook.Inspector Inspector)
{
    Outlook.MailItem tmpMailItem = (Outlook.MailItem)Inspector.CurrentItem;
    if (tmpMailItem != null)
    {
        if (tmpMailItem.EntryID == null)
            Globals.Ribbons.Ribbon1.tab1.ControlId.OfficeId = "TabNewMailMessage";
    }
}

You can read more about adding custom groups to built-in tabs in the following MSDN articles:

How to: Customize a Built-in tab

How to: Get Started Customizing the Ribbon

Ribbon Designer

Customizing a Ribbon for Outlook

Share a Ribbon Customization between Office Applications (Norm Estabrook)

VSTO Team — Mon, 10 Mar 2008 23:01:00 GMT

We have received feedback from several folks that they would like design one Ribbon by using the Ribbon visual designer, and then re-use that same Ribbon in more than one Office application. This approach makes sense. If my custom tab looks the same for each application, I really don’t want to create the same Ribbon in four separate Office projects.

So I poked around to see if this was possible. I caught up with one of developers who created the VSTO Ribbon designer and he showed me exactly how to do it.

First, add a Ribbon to a VSTO project. Then, copy the Ribbon code files to a class library project. Finally, add a reference to the class library assembly from within any VSTO project and voila. Well, it’s a tad more challenging. Here are all the detailed steps.

Create the Ribbon

1. Create a 2007 Excel, Outlook, PowerPoint, or Word project in Visual Studio. For the purpose of these steps, create a C# project and name the project RibbonStarterProject.

2. Add a Ribbon (Visual Designer) item to the project. For the purpose of these steps, accept the default name “Ribbon1”.

3. Save and close the project.

Create a Class Library Project

1. Create a new class library project in Visual Studio. For the purpose of these steps, name the project SharedRibbonLibrary.

2. Add a project reference to the Microsoft.Office.Tools.Common.v9.0 assembly.

3. On the Project Menu in Visual Studio, click Add Existing Item.

4. In the Add Existing Item dialog box, browse to the “RibbonStarterProject” project directory, select the Ribbon.cs file, and click Add.

Ribbon1.cs is copied to the project directory and appears beneath the project node in Solution Explorer.

5. Double-click Ribbon1.cs.

The Ribbon designer appears.

6. From the Office Ribbon Controls tab of the Toolbox, drag a button onto group1.

7. Click button1 to select it.

8. In the Properties window, set Modifiers to Public.

Note: By default, controls that you add to the Ribbon are Internal. That makes them only accessible to code inside the same assembly. However, when you access these controls, you will be accessing them through an assembly reference. Therefore, to reach them from code, you must make them public. More on this soon.

9. Right-click the Ribbon designer, and then click Properties.

10. In the Properties window, click the RibbonType property, and then select the Ribbon ID’s of the applications or Outlook Inspector windows in which you want the Ribbon to appear. For more information about this property, see the MSDN reference topic for the RibbonType property.

11. In Solution Explorer, right-click Ribbon1.cs, and then click View Code.

12. Change the namespace of the class to “SharedRibbonLibrary”.

13. Repeat this step for the Ribbon1.designer.cs file.

14. Compile and save the SharedRibbonLibrary project. You can now use the resulting assembly in any VSTO project that supports the Ribbon.

Consume the Ribbon Customization

1. Create 2007 Excel, Outlook, PowerPoint, or Word project.

2. Add a reference to the SharedRibbonLibrary assembly.

3. Add the following code to the ThisAddin, ThisWorkbook, or ThisDocument class of your project. This code overrides the CreateRibbonExtensibilityObject method and returns the Ribbon to the Office application.

protected override Microsoft.Office.Core.IRibbonExtensibility

CreateRibbonExtensibilityObject()

{

return new Microsoft.Office.Tools.Ribbon.RibbonManager(

new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] { new

SharedRibbonLibrary.Ribbon1() });

}

4. Add a new class to the project. Accept the default name “Class1.cs”.

5. Replace the code in the Class1 file with the following:

partial class ThisRibbonCollection : Microsoft.Office.Tools.Ribbon.RibbonReadOnlyCollection

{

internal SharedRibbonLibrary.Ribbon1 Ribbon1

{

get { return this.GetRibbon<SharedRibbonLibrary.Ribbon1>(); }

}

Ok – You are done! You can now access the Ribbon and the button that you added to the Ribbon in your code. Lets try by handling an event in the consuming project.

Handle the Button Click Event

1. Add the following code to the startup event handler of project.

Globals.Ribbons.Ribbon1.button1.Click += new EventHandler<Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>(button1_Click);

2. Add the following event handler to your project:

void button1_Click(object sender,

Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs e)

{

System.Windows.Forms.MessageBox.Show("I can handle events!");

}

3. Run the project.

4. When the Office application opens, click the Add-Ins tab, and then click your button.

A message that says “I can handle events!” appears.

- Norm Estabrook

Programming Writer for BizApps User Education

Automatically Deploy Any File to SharePoint When you Debug a SharePoint Solution (Norm Estabrook)

VSTO Team — Thu, 31 Jan 2008 22:30:00 GMT

When you debug a SharePoint workflow project, the workflow deployment process copies the feature.xml and workflow.xml to a feature directory on SharePoint. You can configure your solution to deploy other files as well. For example, you might want to deploy InfoPath (*.xsn) files that provide a UI for the workflow, or a file that contains localized resource strings.

To do this, open the feature.xml file of your solution, and add an element named ElementFile for each file that you want to deploy along with your project. Set the Location attribute of the element to the name of the file.

Note If the file is located outside of the root directory of the SharePoint solution, ensure that the name includes a relative path.

The following example specifies an InfoPath form named InitiationForm. This form is located in the root directory of the SharePoint solution so the name does not require a relative file path.

<Feature Id="c8ff5406-135a-4fba-8507-ff4d311434a7"

Title="SharePointFormsWorkflow feature"

Description="My SharePoint Workflow Feature"

Version="12.0.0.0"

Scope="Site"

ReceiverAssembly="Microsoft.Office.Workflow.Feature,

Version=12.0.0.0, Culture=neutral,

PublicKeyToken=71e9bce111e9429c" ReceiverClass="Microsoft.Office.Workflow.Feature.WorkflowFeatureReceiver"

xmlns="http://schemas.microsoft.com/sharepoint/">

<ElementFile Location="InitiationForm.xsn" />

</ElementManifests>

</Properties>

</Feature>

The VSTO documentation has been updated with this information and will appear on MSDN soon.