Walkthrough: Updating the Controls on a Ribbon at Run Time

This walkthrough demonstrates how to use the Ribbon object model to update the controls on a Ribbon after the Ribbon is loaded into the Office application.

Applies to: The information in this topic applies to document-level projects and application-level projects for the following applications: Excel 2013 and Excel 2010; InfoPath 2013 and InfoPath 2010; Outlook 2013 and Outlook 2010; PowerPoint 2013 and PowerPoint 2010; Project 2013 and Project 2010; Visio 2013 and Visio 2010; Word 2013 and Word 2010. For more information, see Features Available by Office Application and Project Type.

The example pulls data from the Northwind sample database to populate a combo box and menu in Microsoft Office Outlook. Items that you select in these controls automatically populate fields such as To and Subject in an e-mail message.

This walkthrough illustrates the following tasks:

Creating a new Outlook add-in project.

Designing a custom Ribbon group.

Adding the custom group to a built-in tab.

Updating controls on the Ribbon at run time.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

The Ribbon for this example will appear when a user composes a new mail message. To create a custom group for the Ribbon, first add a Ribbon item to your project, and then design the group in the Ribbon Designer. This custom group will help you generate follow-up e-mail messages to customers by pulling names and order histories from a database.

To design a custom group

On the Project menu, click Add New Item.

In the Add New Item dialog box, select Ribbon (Visual Designer).

Change the name of the new Ribbon to CustomerRibbon, and then click Add.

The CustomerRibbon.cs or CustomerRibbon.vb file opens in the Ribbon Designer and displays a default tab and group.

Click the Ribbon Designer to select it.

In the Properties window, click the drop-down arrow next to the RibbonType property, and then click Microsoft.Outlook.Mail.Compose.

This enables the Ribbon to appear when the user composes a new mail message in Outlook.

In the Ribbon Designer, click Group1 to select it.

In the Properties window, set Label to Customer Purchases.

From the Office Ribbon Controls tab of the Toolbox, drag a ComboBox onto the Customer Purchases group.

Click ComboBox1 to select it.

In the Properties window, set Label to Customers.

From the Office Ribbon Controls tab of the Toolbox, drag a Menu onto the Customer Purchases group.

In the Properties window, set Label to Product Purchased.

Set Dynamic to true.

This enables you to add and remove controls on the menu at run time after the Ribbon is loaded into the Office application.

A built-in tab is a tab that is already on the Ribbon of an Outlook Explorer or Inspector. In this procedure, you will add the custom group to a built-in tab, and then specify the position of the custom group on the tab.

To add the custom group to a built-in tab

Click the TabAddins (Built-In) tab to select it.

In the Properties window, expand the ControlId property, and then set OfficeId to TabNewMailMessage.

This adds the Customer Purchases group to the Messages tab of the Ribbon that appears in a new mail message.

Click the Customer Purchases group to select it.

In the Properties window, expand the Position property, click the drop-down arrow next to the PositionType property, and then click BeforeOfficeId.

Set the OfficeId property to GroupClipboard.

This positions the Customer Purchases group before the Clipboard group of the Messages tab.

using System.Data.Linq;
using System.Data.Linq.Mapping;
using System.Linq.Expressions;
using Outlook = Microsoft.Office.Interop.Outlook;
using System.Data;
using System.IO;
using Ribbon_Update_At_Runtime.Northwind40DataSetTableAdapters;

Add the following code inside the CustomerRibbon class. This code declares the data table and table adapters that you will use to store information from the Customer, Orders, Order Details, and Product tables of the Northwind database.

When you open a new mail form in Outlook, a custom group named Customer Purchases appears on the Messages tab of the Ribbon.

To create a customer follow-up e-mail message, select a customer, and then select products purchased by the customer. The controls in the Customer Purchases group are updated at run time with data from the Northwind database.

To test the controls in the custom group

Press F5 to run your project.

Outlook starts.

In Outlook, on the File menu, point to New, and then click Mail Message.

The following actions occur:

A new mail message Inspector window appears.

On the Message tab of the Ribbon, the Customer Purchases group appears before the Clipboard group.

The Customers combo box in the group is updated with the names of customers in the Northwind database.

On the Message tab of the Ribbon, in the Customer Purchases group, select a customer from the Customers combo box.

The following actions occur:

The Products Purchased menu is updated to show each sales order for the selected customer.

Each sales order submenu is updated to show the products purchased in that order.

The selected customer's e-mail address is added to the To line of the mail message, and the subject and body of the mail message are populated with text.

Click the Products Purchases menu, point to any sales order, and then click a product from the sales order.