Office Development with Visual Studio : Word 2003

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 …

Visual Studio Command Bar for Arranging Controls on Documents and Worksheets (McLean Schofield)

VSTO Team — Fri, 11 Apr 2008 00:05:00 GMT

One of the lesser-known features of Visual Studio Tools for Office is the Microsoft Office Word and Microsoft Office Excel command bar. When you are developing a document-level project for Word or Excel (for example, a Word Document or Excel Workbook project) and you have the document or one of your worksheets open in the designer, this command bar appears in Visual Studio, just above the designer. In Excel, this command bar looks like the following by default.

The first several buttons in this command bar are for changing the keyboard scheme and mapping XML to the document or worksheet. This post is about the purpose of the rest of the buttons.

If you are designing a custom UI for your document or worksheet that includes Windows Forms controls that you add by using the designer, you can use these buttons to arrange the controls with a single click. When you select multiple controls in the designer, these buttons become enabled.

From left to right, here are the buttons you can use:

Align Lefts. This button moves all of the controls to the left, so that they are aligned with the left side of the left-most control.
Align Centers. This button moves all of the controls left or right so that they are aligned around the vertical axis of the widest control.
Align Rights. This button moves all of the controls to the right, so that they are aligned with the right side of the right-most control.
Align Tops. This button moves all of the controls up, so that they are aligned with the top side of the upper-most control.
Align Middles. This button moves all of the controls up or down, so that they are aligned around the horizontal axis of the tallest control.
Align Bottoms. This button moves all of the controls down, so that they are aligned with the bottom side of the bottom-most control.
Make Horizontal Spacing Equal. The left-most and right-most control remain in place; the controls in between move horizontally so that there is equal horizontal space between each control.
Make Vertical Spacing Equal. The top-most and bottom-most control remain in place; the controls in between move vertically so that there is equal vertical space between each control.

A special note about Word. In Word projects, the alignment buttons are enabled only if the selected controls are not in line with text. By default, controls that you add to a Word document at design time are in line with text. To change the layout style of the control, right-click the control and then click Format Control. Then, on the Layout tab, select a wrapping style other than In line with text:

Examples. Enough words! Here are some examples that show these alignment options in action. These examples are pretty contrived, but they should give you an idea of the effects of each option.

Given the following buttons on a worksheet:

Align Lefts rearranges the controls as follows:

Align Centers rearranges the controls as follows:

And Align Rights rearranges the controls as follows:

Given the following buttons on a worksheet:

Align Tops rearranges the controls as follows:

Align Middles rearranges the controls as follows:

And Align Bottoms rearranges the controls as follows:

Given the following buttons on a worksheet:

Make Horizontal Spacing Equal rearranges the controls as follows:

Finally, given the following buttons on a worksheet:

Make Vertical Spacing Equal rearranges the controls as follows:

I hope these options come in handy then next time you are adding controls to a document or worksheet in VSTO.

-------------------------------------------------

McLean Schofield, Programming Writer