frice's WebLog : Customizing the Ribbon UI

Customizing the Office 2007 Ribbon UI - Part 6

frice — Wed, 28 Jun 2006 18:00:00 GMT

In this topic on customizing the Ribbon UI, we'll look at different scenarios for customizing the Ribbon at the application-level by using COM add-ins. These modifications could just as easily be applied to a specific document with document-level customizations using Office 2007 Open XML Formats files as described in Part 3 of this series.

Note: I would also highly recommend that you check out the three-part series of articles on customizing the Ribbon at: http://msdn.microsoft.com/en-us/library/aa338202.aspx

First, you'll create the project in Visual Studio using C#. Next, you'll create different customization XML markup files and then embed those into the project. As some of the customizations involve using bitmap icons, you'll need to include three of your favorite 16 x 16 pixel icons. Custom icons for add-ins must be 16 x 16 pixels and be either 16-color or True Color. To get started:

First, create the Visual C# project:
1. Start Visual Studio .NET 2005.
2. On the File menu, click New Project.
3. In the New Project dialog box under Project Types, expand Other Projects, click Extensibility Projects, and then double-click Shared Addin.
4. Type a name for the project. In this sample, type RibbonUISamplesCS.
5. In the first screen of the Shared Add-in Wizard, click Next.
6. In the next screen, select "Create an Add-in using Visual C#", and then click Next.
7. In the next screen, clear all of the selections except Microsoft Word and then click Next.
8. Type a Name and Description for the add-in, and then click Next.
9. In the Choose Add-in Options screen, select "I would like my Add-in to load when the host application loads" and then click Next.
10. Click Finish to complete the wizard.

Now add a reference to Word:
1. In the Solution Explorer, right-click References, and then click Add Reference.

Note: If you don't see the References folder, click the Project menu and then Show All Files.

2. Scroll downward on the .NET tab, press the Ctrl key, and then select Microsoft.Office.Interop.Word.
3. On the COM tab, scroll downward, select Microsoft Office 12.0 Object Library, and then click OK.
4. Next add the following namespace references to the project if they don't already exist. Do this just below the namespace line:

using System;
using Extensibility;
using System.Runtime.InteropServices;
using Microsoft.Office.Core;
using Microsoft.Office.Interop;
using System.Drawing;
using System.Windows.Forms;

Implement the IRibbonExtensibility interface.
1. In the Solution Explorer, right-click Connect.cs, and click View Code.
2. At the end of the public class Connect statement, add a comma, and then type IRibbonExtensibility.

Tip: You can use Microsoft IntelliSense to insert interface methods for you. For example, at the end of the public class Connect : statement, type IRibbonExtensibility, right-click, point to Implement Interface, and then click Implement Interface Explicitly. This adds a stub for the only IRibbonExtensibility interface member: GetCustomUI. The implemented method looks like this:

string IRibbonExtensibility.GetCustomUI(string RibbonID)
{
}

3. Insert the following statement into the GetCustomUI method, overwriting the existing code:

return resource.GetString("customui-1.xml");

4. Above the GetCustomUI method, add this statement that gives you access to the XML markup files which you'll add later:

private ResourceManager resource = new ResourceManager();

5. Add the callback methods that will be used in the different customization files:

#region callbacks-1

public stdole.IPictureDisp ButtonImage(IRibbonControl control)
{
return resource.GetImage("Icon2.bmp");
}

public void ButtonAction(IRibbonControl control)
{
Random r = new Random();
string s = r.Next(100000, 200000).ToString();

Microsoft.Office.Interop.Word.Application wordApp = (Microsoft.Office.Interop.Word.Application)(applicationObject);
wordApp.Selection.InsertAfter("\nContoso Case ID " + s);
}

#endregion callbacks-1

#region callbacks-2

private Boolean randomize = false;
private IRibbonUI myRibbon;

public void ribbonLoaded(IRibbonUI ribbon)
{
myRibbon = ribbon;
}

public stdole.IPictureDisp getSButton(IRibbonControl control)
{
return resource.GetImage("Icon3.bmp");
}

public int bankTellers_getItemCount(IRibbonControl control)
{
return 6;
}

public stdole.IPictureDisp bankTellers_getItemImage(IRibbonControl control, int index)
{
Random r = new Random();

   if (!randomize)
   {
      return resource.GetImage(index + ".bmp");
   }
   else
   {
      return resource.GetImage(r.Next(0, 7).ToString() + ".bmp");
   }
}

public void bankTellers_OnAction(IRibbonControl control, int index)
{
   myRibbon.Invalidate();
   Microsoft.Office.Interop.Word.Application wordApp = (Microsoft.Office.Interop.Word.Application)(applicationObject);
   wordApp.Selection.InsertAfter("Officer #" + (index+1) + " ");
   // MessageBox.Show("You just clicked on Bank Teller #" + (index + 1) + "!");
}

public void toggle_randomize(IRibbonControl control, bool press)
{
randomize = press;
myRibbon.Invalidate();
}

public string getRandomizeLabel(IRibbonControl control)
{
   if (randomize)
   {
      return ("Randomize ON");
   }
   else
   {
      return ("Randomize OFF");
   }
}

#endregion callbacks-2

#region callbacks-3
public stdole.IPictureDisp dinoImage(IRibbonControl control)
{
return resource.GetImage("Icon1.bmp");
}

public stdole.IPictureDisp OnLoadImage(string image)
{
return resource.GetImage(image);
}

#endregion callbacks-3

Now, we'll start creating different customization files, embedding them as resources in the project, and then observing how they impact the Ribbon UI:

1. In a text editor, add the following XML markup:

<?xml version="1.0" encoding="utf-8" ?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">
<ribbon>
    <tabs>
      <tab idMso="TabInsert">
        <group id="MyContosoGroup" label="Contoso!" insertAfterMso="GroupHeaderFooter">
          <button id="CInsertCaseID"
                 size="large"
                  label="Case ID Number"
                  screentip="Insert Contoso Case ID Number."
                  onAction="ButtonAction"
                  getImage="ButtonImage" />
        
      </group>
      </tab>
    </tabs>
</ribbon>
</customUI>

2. Close and save the file as customUI-1.xml.
3. In the Solution Explorer in the project, right-click RibbonUISamplesCS, point to Add, and then click Existing Item.
4. Navigate to the customUI-1.xml file you created, select the file, and then click Add.

For each of the customization files you create, you will repeat these steps. After adding each file and before building and installing the project, you'll need to ensure that the GetCustomUI method points to the correct file. So in this instance, the statement in the GetCustomUI method will read:

return resource.GetString("customui-1.xml");

And finally, use the same procedures to add each of the three 16 x 16 bitmaps as Icon1.bmp. Icon2.bmp, and Icon3.bmp, respectively.

Compile both the add-in and its setup project. Before beginning, make sure that Word is closed.
1. In the Project menu, click Build Solution. You will see a message when the build is complete in the system tray in the lower left corner of the window.
2. In the Solution Explorer, right-click RibbonSamplesCSSetup and click Build.
3. Right-click RibbonSamplesCSSetup and click Install. This launches the RibbonSamplesCSSetup Setup Wizard screen.
4. Click Next on all of the screens and then Close on the final screen.
5. Start Word. You should see the "My Tab" tab to the right of the other tabs.

If you have problems with any of this, recheck that the procedures in the project match those in the steps or go back to part 4 in this series of articles for additional troubleshooting steps.

Customizing the Office 2007 Ribbon UI - Part 5

frice — Wed, 21 Jun 2006 18:00:00 GMT

In the previous blog, I created a COM add-in in managed C# code that customized the Ribbon UI regardless of which document was open. In this topic, I use the same customization XML and create the add-in in Visual Basic 6.0. The existing Ribbon UI in Word 2007 is modified by adding a custom tab, custom group, and button. When you click the button, a company name is inserted into the document. To get started, follow these steps:

1. Start Microsoft Visual Basic 6.0 and select Addin as the project type. This will add a designer class to the project (Connect) and a form (frmAddin).
2. In the Project Explorer window, open the Designer window by right-clicking Connect and then select View Object. Select Microsoft Word from the Application drop-down list.
3. In the Initial Load Behavior drop-down list, select Startup.
4. In the Project Explorer, right-click MyAdd and in the Property window change the name of the add-in to RibbonSampleVB.
5. Remove frmAddin from the project.
6. From the Project window, right-click the Connect item and select view code.
7. Remove all of the code in the designer's code window. This code works for Visual Basic add-ins but not Microsoft Office add-ins.
8. Add the following statement to the OnConnection method to obtain a reference to Word when the add-in loads:

Set oWD = Application

9. This step is optional however if you want to be notified that your add-in is actually loading when you start Word, you can add the following statement in the OnConnection procedure. Once you're satisfied that the add-is being loaded, you can remove the line and rebuild the project:

MsgBox "My Addin started in " & Application.Name

10. Next, at the top of the code window, add the following statements to set aside memory for the application object we added earlier and to create a reference to the Ribbon UI interface:

   Dim oWD As Object

   Implements IRibbonExtensibility

11. Next, you'll implement the IRibbonExtensibilty interface's only member: GetCustomUI

   Public Function IRibbonExtensibility_GetCustomUI(ByVal RibbonID As String) As String
      IRibbonExtensibility_GetCustomUI = GetRibbonXML()
   End Function

This procedure calls the GetRibbonXML method that, as it's name implies, returns the customization XML to the GetCustomUI method which then gives it to the Ribbon UI to implement when the add-in loads.

12. Add the GetRibbonXML function. In this instance, the customization code is stored in a string variable that is returned to the GetCustomUI method:

Public Function GetRibbonXML() As String
Dim sRibbonXML As String

    sRibbonXML = "<customUI xmlns=""http://schemas.microsoft.com/office/2006/01/customui"" >" & _
                "<ribbon>" & _
                "<tabs>" & _
                "<tab id=""CustomTab"" label=""My Tab"">" & _
                "<group id=""SampleGroup"" label=""Sample Group"">" & _
                "<button id=""Button"" label=""Insert Company Name"" size=""large"" onAction=""InsertCompanyName"" />" & _
                "</group >" & _
                "</tab>" & _
                "</tabs>" & _
                "</ribbon>" & _
                "</customUI>"

   GetRibbonXML = sRibbonXML

   End Function

13. Now, add the procedure that gets called when you click the button in the custom tab:

Public Sub InsertCompanyName(ByVal control As IRibbonControl)
   ' Inserts the specified text at the beginning of a range or selection.
   Dim MyText As String
   Dim MyRange As Object
   Set MyRange = oWD.ActiveDocument.Range
   MyText = "Microsoft Corporation"
   ' Selection Example:
   'Selection.InsertBefore (MyText)
   ' Range Example: Inserts text at the beginning
   ' of the active document.
   MyRange.InsertBefore (MyText)
End Sub

14. To make sure the code compiles without error, on the Run menu, click Start with Full Compile.
15. Once the code compiles without error, save the project and create the RibbonSampleVB.dll by clicking the File menu and then clicking Make RibbonSampleVB.dll. The designer will register the add-in for you.
16. Start Word. You should see the "My Tab" tab to the right of the other tabs.
17. Click on the tab and then click the Insert Company Name button. The company name is inserted into the document.

If you have trouble loading the add-in or if the button doesn't work, you may need to do one of the following:

1. Go to the Trust Center to enable macros. Click the Microsoft Office Button (this is the round button in the upper left of the screen).
2. Click Trust Center, click Macro Settings, and then select the "Disable all macros with notification" and the "Trust access to the VBA project object model" options.
3. Close and reopen the document.

If you don’t see the My Tab tab when you start Word, you may need to add an entry to the registry. To do this, perform the following steps:

Caution: The next few steps contain information about modifying the registry. Before you modify the registry, be sure to back it up and make sure that you understand how to restore the registry if a problem occurs. For information about how to back up, restore, and edit the registry, search for the following article in the Microsoft Knowledge Base: 256986 Description of the Microsoft Windows Registry.

1. On the desktop click Start, click Run, and type regedit.
2. From the Registry tab, navigate to the following registry key for the add-in:

HKCU\Software\Microsoft\Office\Word\AddIns\RibbonXSampleVB.Connect

Note: If the RibbonXSampleVB.Connect key does not exist, you can create it. To do so, right-click the Addins folder, point to New, and then click Key. Name the key RibbonXSampleVB.Connect. Add a LoadBehavior DWord and set its value to 3.

And that's all there is to creating a COM Add-in to customize the Ribbon UI. In the next blog in this series, we'll look at additional properties of the Ribbon UI and XML markup you use to further customize the Ribbon UI.

Customizing the Office 2007 Ribbon UI - Part 4

frice — Wed, 14 Jun 2006 18:00:00 GMT

In this installment in the series on customizing the Ribbon UI, we'll look at adding application-level customization. In the previous blog, we detailed the steps to create document-level Ribbon by modifying an Open XML Formats macro-enabled file in Word 2007. In this blog, we will create application-level customizations using a managed COM add-in which we'll create in Microsoft Visual Studio 2005 using C#. For consistency, we'll use the same customization that we used in the previous blog; namely adding a custom tab, a custom group, and button that will insert a company name into a Word 2007 document at the beginning of the document. This is the procedure:

1. In a text editor, add the following XML markup:

2. Close and save the file as customUI.xml.

Now create the Visual C# project to modify the Ribbon UI:
1. Start Visual Studio .NET 2005.
2. On the File menu, click New Project.
3. In the New Project dialog box under Project Types, expand Other Projects, click Extensibility Projects, and then double-click Shared Addin.
4. Type a name for the project. In this sample, type RibbonXSampleCS.
5. In the first screen of the Shared Add-in Wizard, click Next.
6. In the next screen, select "Create an Add-in using Visual C#", and then click Next.
7. In the next screen, clear all of the selections except Microsoft Word and then click Next.
8. Type a Name and Description for the add-in, and then click Next.
9. In the Choose Add-in Options screen, select "I would like my Add-in to load when the host application loads" and then click Next.
10. Click Finish to complete the wizard.

Now add a reference to Word:
1. In the Solution Explorer, right-click References, and then click Add Reference.

using System.Reflection;
using Microsoft.Office.Core;
using System.IO;
using System.Xml;
using Extensibility;
using System.Runtime.InteropServices;
using MSword = Microsoft.Office.Interop.Word;

Add the XML customization file as an embedded resource in the project by following these steps:
1. In the Solution Explorer, right-click RibbonXSampleCS, point to Add, and click Existing Item.
2. Navigate to the customUI.xml file you created, select the file, and then click Add.
3. In the Solution Explorer, right-click customUI.xml, and then select Properties.
4. In the properties window select Build Action, and then scroll down to Embedded Resource.

Next, to get access to its members, you need to implement the IRibbonExtensibility interface.
1. In the Solution Explorer, right-click Connect.cs, and click View Code.
2. Just below the Connect method, add the following declaration which creates a reference to the Word application object:

private MSword.Application applicationObject;

3. Add the following line to the OnConnection method. This statement creates an instance of the Application object:

applicationObject =(MSword.Application)application;

4. At the end of the public class Connect statement, add a comma, and then type IRibbonExtensibility.

string IRibbonExtensibility.GetCustomUI(string RibbonID)
{
}

5. Insert the following statement into the GetCustomUI method, overwriting the existing code:
return GetResource("customUI.xml");

6. Insert the following method below the GetCustommUI method:

        private string GetResource(string resourceName)
        {
            Assembly asm = Assembly.GetExecutingAssembly();
            foreach (string name in asm.GetManifestResourceNames())
            {
                if (name.EndsWith(resourceName))
                {
                    System.IO.TextReader tr = new System.IO.StreamReader(asm.GetManifestResourceStream(name));
                    //Debug.Assert(tr != null);
                    string resource = tr.ReadToEnd();

                    tr.Close();
                    return resource;
                }
            }
            return null;
        }

Note: The GetCustomUI method calls the GetResource method. The GetResource method sets a reference to this assembly during runtime and then loops through the embedded resource until it finds the one named "customUI.xml." It then creates an instance of the StreamReader object that reads the embedded file containing the XML markup. The procedure passes the XML back to the GetCustomUI method which returns the XML to the Ribbon. Alternately, you can also construct a string that contains the XML markup and read it directly in the GetCustomUI method.

7. Following the GetResource method, add this method. This method inserts the company name into the document at the beginning of the page:

        public void InsertCompanyName(IRibbonControl control)
        {
        // Inserts the specified text at the beginning of a range.
            string MyText;
            MyText = "Microsoft Corporation";

MSword.Document doc = applicationObject.ActiveDocument;

            //Inserts text at the beginning of the active document.
            object startPosition = 0;
            object endPosition = 0;
            MSword.Range r = (MSword.Range)doc.Range(
                   ref startPosition, ref endPosition);
            r.InsertAfter(MyText);
        }

Compile both the add-in and its setup project. Before beginning, make sure that Word is closed.
1. In the Project menu, click Build Solution. You will see a message when the build is complete in the system tray in the lower left corner of the window.
2. In the Solution Explorer, right-click RibbonXSampleCSSetup and click Build.
3. Right-click RibbonXSampleCSSetup and click Install. This launches the RibbonXSampleCSSetup Setup Wizard screen.
4. Click Next on all of the screens and then Close on the final screen.
5. Start Word. You should see the "My Tab" tab to the right of the other tabs.

To test the project:
Click the "My tab" tab and then click the "Insert Company Name" button. The company name is inserted into the document at the cursor location.

If you don’t see the customized Ribbon UI, you may need to add an entry to the registry. To do this, perform the following steps:

1. In the Solution Explorer, right click on the setup project, RibbonXSampleCSSetup, point to View, and then click Registry.
2. From the Registry tab, navigate to the following registry key for the add-in:

HKCU\Software\Microsoft\Office\Word\AddIns\RibbonXSampleCS.Connect

Note: If the RibbonXSampleCS.Connect key does not exist, you can create it. To do so, right-click the Addins folder, point to New, and then click Key. Name the key RibbonXSampleCS.Connect. Add a LoadBehavior DWord and set its value to 3.

And that's all there is to creating a COM Add-in to customize the Ribbon UI. In the next blog in this series, we'll look at customizing the Ribbon UI by using a COM add-in created in Visual Basic.

Customizing the Office 2007 Ribbon UI - Part 3

frice — Wed, 07 Jun 2006 18:00:00 GMT

In this blog, I will walk through an example of adding a custom tab, custom group, and a button with a simple callback procedure to the Ribbon in a Word 2007 document. To get started:

1. Create the customization file in any text editor by adding the following XML markup to the file. Save the file as customUI.xml.
2. Add the following XML markup to the file:

3. Create a folder on your desktop named customUI and copy the XML customization file to the folder.
4. Validate the XML markup with a custom UI schema.
Note: This step is optional. For an example of tools you can use to validate XML markup, see the XSD Schema Validator on this Web site: http://apps.gotdotnet.com/xmltools/xsdvalidator.

5. Create a document in Word 2007 and save it with the name RibbonSample.docm.
6. Open the Visual Basic Editor and add the following procedure to the ThisDocument code module.

Sub InsertCompanyName(ByVal control As IRibbonControl)
   ' Inserts the specified text at the beginning of a range or selection.
   Dim MyText As String
   Dim MyRange As Object
   Set MyRange = ActiveDocument.Range
   MyText = "Microsoft Corporation"
   ' Range Example: Inserts text at the beginning
   ' of the active document
   MyRange.InsertBefore (MyText)
   ' Selection Example:
   'Selection.InsertBefore (MyText)
End Sub

7. Close and save the document.
8. Add a .zip extension to the document file name and double-click to open the file.
9. Add the customization file to the container by dragging the customUI folder from the desktop to the Zip file.
10. Extract the .rels file to your desktop. A _rels folder containing the .rels file is copied to your desktop.
11. Open the .rels file and add the following line between the last <Relationship> tag and the <Relationships> tag. This creates a relationship between the document file and the customization file:

12. Close and save the file.
13. Add the _rels folder back to the container file by dragging it from the desktop, overwriting the existing file.
14. Rename the document file to its original name by removing the .zip extension.
15. Open the document and notice that the Ribbon UI now displays the My Tab tab.
16. Click the tab and notice the Sample Group group with a button control.
17. Click the button and the company name is inserted into the document.

As you can see, adding your own customizations to the Ribbon UI is very easy. In the next blog, we'll look at adding additional controls and working with existing components.

Customizing the Office 2007 Ribbon UI - Part 2

frice — Wed, 31 May 2006 18:00:00 GMT

In the previous blog, I discussed reasons for the new Office Ribbon UI, ways to customize the Ribbon, parts of the Ribbon, and gave an example of an XML customization file. In this blog, I'll talk some about callback procedures that give the Ribbon's controls and components functionality.
A callback is a way of telling one procedure, say procA, where to send messages when procA has completed a task. It's just like giving someone a job to do and also giving them a contact number where they can reach you once the job has been completed. Consider the case of the onAction callback procedure for a button. When you click the button, the callback procedure specified for the onAction event is called and executed. When the task has completed, the procedure notifies and passes control back to the Ribbon.
In the example I gave in the previous blog, the Launcher1 button specified an onAction callback procedure named "AdditionalWidgetOptions." When you click the button, the callback procedure, which resides in your document, is called. The procedure performs whatever task it has been given, for example setting text to bold, and then notifies the Ribbon that the task has been completed and returns control back to the Ribbon.
Now lets briefly look at sample code that supports the XML markup. This particular sample is a portion of an add-in class created as managed C# code in Visual Studio but could just as easily be created in Visual Basic, Visual C++, any of the .NET languages, or VBA. The IDTExtensibility2 implementations have been left out in order to make the example less cluttered:

public class Connect : Object, Extensibility.IDTExtensibility2, IRibbonExtensibility
{
   public string GetCustomUI()
   {
      StreamReader customUIReader = new System.IO.StreamReader("C:\\Visual Studio Projects\\RibbonXSampleCS\\customUI.xml");
      string customUIData = customUIReader.ReadToEnd();
      return customUIData;

#region Ribbon callbacks

   public void ButtonOnAction(IRibbonControl control)
   {
      MessageBox.Show("Button clicked: " + control.Id);
   }

   public void ToggleButtonOnAction(IRibbonControl control, bool pressed)
   {
      if (pressed)
         MessageBox.Show("ToggleButton pressed.");
      else
         MessageBox.Show("ToggleButton un-pressed.");
   }

   public void EditBoxOnChange(IRibbonControl control, string text)
   {
      ///Do something with 'text' here.
   }

#endregion
}

First, the class must implement the Extensibility.IDTExtensibility2 and IRibbonExtensibility interfaces. Anyone who has created add-ins is already familiar with implementing the IDTExtensibility2 interface. The IRibbonExtensibility interface exposes the GetCustomUI method. The GetCustomUI method is the only method defined in the IRibbonExtensibility interface. In this example, it creates an instance of the System.IO.StreamReader that reads a file containing the XML markup. The method stores the XML customization markup in a variable named customUIData. You could also construct a string containing the XML markup or open an embedded resource (a file contained in the project itself) to supply the XML markup. The sample also includes three callback procedures. The first, ButtonOnAction, receives an object representing the button pressed and displays a message showing the id of the control. The next procedure, ToggleButtonOnAction, receives the toggleButton object and a boolean indicating whether the togglebutton was pressed and then displays a message in a dialog box. The third procedure is a stub procedure that is called when the contents of an editBox control changes. An object representing the clicked control is passed in as well as the text in the editBox. You can see that the process is easily understood and easy to implement based on your needs.

In this topic, I've discussed the basic of implementing callbacks to add functionality to the Ribbon UI. In the next topic, I will dive into customizing the Ribbon in Word by adding a button control with a simple callback procedure.

Customizing the Office 2007 Ribbon UI - Part 1

frice — Thu, 25 May 2006 00:36:00 GMT

This is the first in a series of topics focusing on the new Office 2007 user interface (UI) and Ribbon extensibility, also called RibbonX. By now, you've probably seen blogs, press releases, and other information on the virtues and benefits of the new Ribbon UI. In previous versions of Office, adding custom commands using COM add-in and command bars could be a daunting task for novice Office developers. RibbonX is a breeze. The basic structure of the Ribbon is a hierarchical model, consisting of tabs containing groups of commands and controls displayed in logical, easy-to-find groupings using familiar controls such as drop down dialog boxes, buttons, and context (right-click) menus. The Ribbon also includes rich, interactive new controls called galleries that allows you to see what a change will look like in your document before you actually commit the change. Solutions created in previous versions of Office continue to work and are added to an "Add-Ins" tab. Context menus provide rich, commands and controls relative to the section of the document you are working in.

Note: Some of these features, such as context (right-click) menus, the mini-Toolbar, the Status Bar and live preview using galleries, are not available when customizing the Ribbon UI with add-ins.

Customizing the Ribbon UI is really easy. You can customize the Ribbon through combination of XML markup and any .NET language supported in Microsoft Visual Studio such as Visual Basic .NET, Visual C++, and C#. You can also customize the Ribbon UI using Microsoft Visual Basic for Applications (VBA) and Visual Basic 6.0. There are essentially two ways to customize the Ribbon, both of which at their core use XML markup: directly through a valid Office XML Open File Format file and COM add-ins either containing XML markup or reading XML from a file. Using Office XML Open File Format files allows you to add customizations by using templates (such as .xlam, .dotm files). In this topic, I'll just talk a little about the XML. I'll go into more detail on the XML and code used to create specific UIs.

Before looking at RibbonX, I'll describe a little about some of the parts of the new UI. The Office 2007 UI is more than just the Ribbon; it is a combination of new and traditional features. For example, there is the Office Menu, available from the round Microsoft Office Button located in the upper left-corner of the application window, similar to the File menu found in previous versions of Office. This menu contains the customary New, Open, Save, and Print commands as well as additional commands like Publish, Send, and Finalize. Also in the upper left-corner of the application window is a customizable feature called the Quick Access Toolbar (QAT). The QAT exposes those controls that you typically use frequently such as Save, Undo, Repeat, and Print. The Ribbon includes enhanced versions of the familiar tool tips, called screen tips, that let you display the name and purpose of the control or command. There is a status bar of status indicators (Caps lock, Num Lock), statistics (page number, line number, column) and functions (count, average, sum). Note that the status bar is not customizable. And just as in Office 2003, there are rich, context (right-click) menus. To make it easier for users to find the options they need, they can access legacy dialog boxes in some of the groups by clicking a launcher control in the lower-right corner of some of the groups.

The actual Ribbon customization is done in declarative XML markup. That is, adding a line or encapsulated section to the XML markup in a customization file adds or hides a control, command, or option on the Ribbon. Attributes are used to identify, define characteristics, and add functionality. Writing XML is typically much easier than writing traditional code for many people. And because it's just text, you can write it in any text editor. Additionally, you can take advantage of the many utilities available to help you write and validate XML and associated XSDs such as those provided by Visual Studio Tools for Office.

RibbonX uses callbacks to provide its functionality such as provide status, update properties, or perform some action. Some callbacks look and act like the event procedures you see in other languages. You specify the callback as an attribute of an XML tag in the customization file and then define the callback in code in either the add-in, in a template, or in macro-enabled Office 2007 Open XML Formats file. For example, the XML markup for a button control can specify an onAction attribute that points to a procedure in code which is executed when the button is clicked. That procedure then calls back to the Ribbon to either provide a status or modify the Ribbon.

The following XML markup hides a built-in tab, adds a custom tab containing a custom group containing a custom button, a togglebutton, and a combo box with options.

</group>
</tabs>
</ribbon>
</customUI>

One of the first things you see is a <Ribbon> tag with a startFromScratch="false" attribute. Setting this attribute to True hides the built-in Ribbon controls so that you can build your own UI from scratch. The default for this attribute is False so it is included here for illustration purposes. Next, you see a built-in tab, identified as such by the idMso identifier. There is also an id identifier. The id identifier indicates a custom component. The tab contains a custom group that contains two built-in controls: Paste and Copy.

Next comes a built-in tab containing a custom group. The group contains a number of controls. Notice that the group uses a fully qualified name prepended with the namespace alias. The group contains a button and toggleButton with various attributes defined such as label text and the size of the button. Also included is an event declaration that makes a method call when the user clicks the button. The callback method is implemented in a COM add-in or in the code part of an Open XML Formats file.

A combo box control is added to the tab with three options. The combo box defines different attributes such as its label and a screen tip. And finally, we included a dialog box launcher control for the group that can be used to display a dialog box with additional options.

Looking at this markup, you can see how simple it is to see what's going on here and how easy it would be to add you own controls or adjust the properties of existing components. If you wanted to hide a built-in control, all you would need to do is set its visible attribute to False. In the next blog, I'll discuss callbacks procedures and how they are used, and then get into some examples of creating and modifying different commands and controls on the UI.