Ty Anderson

Customizing Outlook 2010 and 2013 Ribbon tabs, buttons, groups: C#, VB.NET

It’s a new year with new goals. Many people will commit to losing weight or learning a new skill or being a better person. Some won’t commit to anything. It is just another year after all… ho hum.

If you are in the first group, this article is for you. I think, after completing this sample, you will have:

  • Lost weight
  • Learned something new
  • Become a (slightly) better person.

Today, I offer you an Office Developer’s workout. We have a warm-up followed by two all-out sprints. The focus of today’s workout is the Outlook Ribbon. I want to run you through some laps so you know what the Outlook 2010 Ribbon and Outlook 2013 Ribbon (and you along with it) are capable of doing.

Supported ribbon controls & when to use them

The Ribbon revolutionized the Office user interface when originally introduced in Office 2007. Using Visual Studio’s out-of-the-box tools, you can build custom ribbons for your solutions. BUT… Microsoft provides visual designers for a small subset of ribbon controls. Meaning, you will need to write lots of XML to complete your customization.

Add-in Express tools provide visual designers for all Office ribbon controls. It’s a true RAD experience.

Containers

  • Ribbon tab (ADXRibbonTab) – tabs group commands for performing a specific task.
  • Ribbon group (ADXRibbonGroup) – groups are for putting related commands in the same bucket, or group.
  • Ribbon box (ADXRibbonBox) – allows you to align child controls horizontally or vertically. If you set it to vertical alignment, it will create multiple columns if there isn’t enough space for all the child controls.
  • Ribbon Button Group (ADXRibbonButtonGroup)groups buttons into a cohesive unit.
  • Ribbon Button (ADXRibbonButton) – it’s a button. If I need to explain it we got big problems. You can place a button in a box, ButtonGroup, DialogBoxLauncher,Gallery, SplitButton, and Menu controls.
  • Ribbon label (ADXRibbonLabel) – it’s a label. Kind of boring but essential.
  • Ribbon check box (ADXRibbonCheckBox) – it’s a checkbox. You use it to toggle between two states.
  • Ribbon edit box (ADXRibbonEditBox) – this control is a text box. You use it to capture input from the user. What you do with the input is up to you.
  • Ribbon combo box (ADXRibbonComboBox) – it’s a ComboBox control. It contains a list of values the user can select. If they type in the box, the control performs a “quick match” for ease of selection.
  • Ribbon drop down (ADXRibbonDropDown) – pretty much the same as the ComboBox except it does not accept user input.
  • Ribbon gallery (ADXRibbonGallery) – it’s ComboBox with pictures. It’s great if your commands are visual in nature… say, for example, colors or charts or something along those lines.
  • Ribbon menu (ADXRibbonMenu) – a container for pre-defined list of commands. It hosts child controls.
  • Ribbon split button (ADXRibbonSplitButton) – it’s like the Menu but it’s also like a button. It will either execute or command or it will display a cascading list of options. This is great for keeping related commands together. Also, it can toggle.
  • Ribbon separator (ADXRibbonSeparator) – a vertical line that provides a visual separation between controls.
  • Ribbon menu separator (ADXRibbonMenuSeparator) – a horizontal line that provides a visual separation between controls.

Menus

  • Ribbon menu (ADXRibbonMenu) – a container for pre-defined list of commands. It hosts child controls.
  • Ribbon split button (ADXRibbonSplitButton) – it’s like the Menu but it’s also like a button. It will either execute or command or it will display a cascading list of options. This is great for keeping related commands together. Also, it can toggle.
  • Ribbon separator (ADXRibbonSeparator) – a vertical line that provides a visual separation between controls.
  • Ribbon menu separator (ADXRibbonMenuSeparator) – a horizontal line that provides a visual separation between controls.
  • Ribbon dialog box launcher (ADXRibbonDialogBoxLauncher) – you can add this control to any Ribbon group. When clicked it loads a dialog box of your making and choosing. The idea is to provide additional and/or advanced options in the dialog box.

Separators and stuff

  • Ribbon separator (ADXRibbonSeparator) – a vertical line that provides a visual separation between controls.
  • Ribbon menu separator (ADXRibbonMenuSeparator) – a horizontal line that provides a visual separation between controls.
  • Ribbon dialog box launcher (ADXRibbonDialogBoxLauncher) – you can add this control to any Ribbon group. When clicked it loads a dialog box of your making and choosing. The idea is to provide additional and/or advanced options in the dialog box.

The warm-up: Creating an Outlook add-in project

For this project, we want to use Add-in Express for Office and .NET. Open Visual Studio (I’m using Visual Studio 2012) and create a new ADX COM Add-in project. Name the project OutlookRibbons and click OK. After VS creates the project, open the AddInModule in design view.

There is a lot of clickin’ & configuratin’ (aka C&C) in our very near future. We want to grease the skids by adding two ImageList controls. We need two because we need two different sizes of images (32×32 and 16×16). You have a choice. You can either A) download the sample project and copy & paste its ImageList controls into your project (this is what I would do) or B) do the following to add the icons:

  1. Add an ImageList control to the AddinModuledesigner surface. We need to change two properties:
    • ColorDepth = Depth32Bit
    • ImageSize = 32, 32
  2. Open the Images collection of ImageList1 and add nine 32×32 images. I recommend using images from the Visual Studio Image Library. Choose images that make you happy.
  3. Add another ImageListcontrol and use these properties:
    • ColorDepth = Depth16Bit
    • ImageSize = 16, 16
  4. Open its Images collection and add three 16×16 images.

Okay. We have icons. The skids are greased. Let’s do some C&C.

Sprint #1 :: Working with all sorts of buttons

Our first Outlook ribbon tab is all about buttons. Regular buttons, split buttons, button groups, button boxes. The idea here is to show a few configurations and show-off how easy Add-in Express designer makes this process.

Adding a custom ribbon tab

  1. In the AddinModule, click the AdxRibbonTab button to add a tab to the designer surface.
  2. Click the AdxRibbonTab1 component to display its visual designer. If you don’t see it at the bottom of the AddinModule, you’ll need to click the chevron in the lower right-hand corner.
  3. In the designer, select the tab labeled AdxRibbonTab1. In the properties window change the follow properties:
    • Caption = Tab #1
    • Ribbons = OutlookExplorer; OutlookMailCompose; OutlookMailRead

Just Buttons group

  1. Add an AdxRibbonGroup to AdxRibbonTab1. Change its caption to Just Buttons Group.
  2. Select the AdxRibbonGroup and add an AdxRibbonButton to it. Set the button’s properties as follows:
    • Caption = Large Button
    • ImageList = ImageList1
    • Image = 1
    • Size = Large

Three buttons remain for you to add to this group. The image below shows how they should look. Repeat step 5 three times except leave these buttons as standard sized buttons.

A custom Outlook ribbon group with 4 buttons

Lots of Buttons group

Okay, let’s do this again but with different controls. We’ll start again with step #1.

  1. Add a new ribbon group (AdxRibbonGroup). Set its Caption property to Lots of Buttons Group.
  2. Add a button group (AdxRibbonButtonGroup) control.
  3. Select the button group and then add three ribbon buttons (AdxRibbonButton) within it. Change their properties according the following table, remember to set ToggleButton = True for the 3rd button to make it a toggle button.
IMAGE IMAGELIST SHOWCAPTION
BUTTON 1 0 ImageList2 False
BUTTON 2 1 ImageList2 False
BUTTON 3 2 ImageList2 False

All of sudden, we have a toggle button! Hopefully your Outlook Ribbon looks like this:

A custom Outlook ribbon group with 3 image buttons, a split button and a toggle button

Button Box group

This group will contain a nine (9) buttons arranged 3×3. I think the easiest way to tackle this grouping is to add the list of all the buttons and their configurations in a table. We are going to add a ribbon group with 3 ribbon boxes, each containing 3 buttons. The 1st box is aligned vertically, 2nd horizontally, and 3rd vertically again.

RIBBON BOX LOCATION CAPTION IMAGELIST IMAGE SHOWCAPTION
ADXRIBBONBUTTON #1 First BB Button 1 ImageList2 0 True
ADXRIBBONBUTTON #2 First BB Button 2 ImageList2 2 True
ADXRIBBONBUTTON #3 First BB Button 3 ImageList2 1 True
ADXRIBBONBUTTON #4 Second ImageList2 2 False
ADXRIBBONBUTTON #5 Second ImageList2 0 False
ADXRIBBONBUTTON #6 Second ImageList2 2 False
ADXRIBBONBUTTON #7 Third BB Button 7 ImageList2 1 True
ADXRIBBONBUTTON #8 Third BB Button 8 ImageList2 2 True
ADXRIBBONBUTTON #9 Third BB Button 9 ImageList2 0 True

A custom Outlook ribbon tab with all sorts of buttons at design time

Sprint #2 :: Combo box, drop-down, check box, edit box etc.

The second tab of our custom Outlook ribbon contains non-button controls. You probably won’t use them as often as you use buttons but they are handy when you need them.

  1. Start this tab by adding a new AdxRibbonTab component to the AddinModule designer.
  2. Select AdxRibbonTab2to display its designer. In the designer, click the tab and set these properties
    • Caption = Tab #2
    • Ribbons = OutlookExplorer; OutlookMailCompose; OutlookMailRead

Other Ribbon Controls group

  1. Now add an AdxRibbonGroup control to the Tab. Set its Caption to Other Ribbon Controls.
  2. Next add these controls to the group:
    • AdxCheckBox
    • AdxRibbonEditBox
    • AdxRibbonSeparator
    • AdxRibbonComboBox
    • AdxRibbonDropDown
    • AdxRibbonDialogBoxLauncher

For the combo box and drop down, open the Items property collection in the property window and click the ellipses button to open the AdxRibbonItem Collection Editor window. Add a few items and set their properties as you see fit.

We are now finished with this group. It should look something like this:

A custom Outlook ribbon group with a combo box, drop-down, check box and edit box controls

Now let’s tackle the task of creating a gallery.

Gallery group

The Gallery control is a gorgeous control but is probably rarely used. This control is like a pretty girl at a high school dance that never gets to dance because all the guys are too timid to ask her! This is silly at a dance and it is silly here too. Let’s dance!

  1. Add a new AdxRibbonGroup and set its Caption to Gallery.
  2. Add an AdxRibbonGallerycontrol to the Gallery group.
    • Caption = Gallery
    • Columns = 2
    • ImageList = ImageList1
    • Image = 3
    • Rows = 2
    • Size = Large
    • ShowItemCaption = False
    • Open AdxRibbonGallery control’s Items collection. In the AdxRibbonItem Collection Editor, add four (4) new items. Configure their properties according to this table:
CAPTION IMAGE IMAGELIST
ADXRIBBONITEM1 Chart ImageList1 4
ADXRIBBONITEM2 Hierarchy ImageList1 5
ADXRIBBONITEM3 Gauge ImageList1 8
ADXRIBBONITEM4 Database ImageList1 7
  1. Add an AdxRibbonButtonto the ribbon gallery control. Its properties are:
    • Caption = Just Staple it
    • ImageList = ImageList1
    • Image = 6

A Gallery control added to a custom Outlook ribbon

Almost done. I’ll make it quick.

Menu group

  1. Add one last AdxRibbonGroup control to Tab #2… Change its Caption to Menu.
  2. Add an AdxRibbonMenu to the group. Set these properties:
    • Caption = Large Menu
    • ImageList = ImageList1
    • Image = 3
    • Size = Large
  3. This is the last step. It’s kinda like the last round of fireworks when they let loose with everything they have left. With the menu selected, add the following controls and change their Captionto text formatted bold.
    • AdxRibbonButton :: Child Button
    • AdxRibbonSplitButton :: Child Split Button
    • AdxRibbonCheckBox :: Child Check Box
    • AdxRibbonGallery :: Child Gallery
    • AdxRibbonButton :: My Caption
    • AdxRibbonMenu :: Child Menu

With this last control, I wanted to make sure you saw that you can use more than buttons as child controls.

A custom Outlook ribbon tab with non-button controls at design time

If you want to see it in Outlook, just click Build > Register ADX Project in the Visual Studio menu. This command will build the add-in and register it on your system. Then open Outlook and voila!

Outlook 2013 ribbon tab with 3 groups containing all sorts of buttons:

A custom ribbon tab with button controls in Outlook 2013

A custom ribbon tab with various non-button controls in Outlook 2013:

A custom ribbon tab with non-button controls in Outlook 2013

If you already had Outlook open you will need to shut it down and the re-open before you get your voila!

Available downloads:

This sample Outlook add-in was developed using Add-in Express for Office and .net:

Custom Outlook Ribbons sample in VB.NET

You may also be interested in:

11 Comments

  • Rene says:

    Hi,

    thanks for this great example! I have one question. Is it possible to add a
    Button to the Standard MS Outlook Toolbar “Start” where you can also find the
    “Create new Mail” Button?

    Thanks a lot
    Best Regards
    Rene

  • Ty Anderson says:

    Hello Rene

    Yes, this scenario is possible.
    First, you need to ID the portion of the ribbon you want to customize.
    In your case you want to add a button to the TabMail tab’s GroupMailNew group

    I know this because MSFT publishes a list of Office Ribbon Control IDs here:
    https://www.microsoft.com/en-us/download/details.aspx?id=36798

    Good luck out there,

    Ty

  • Ramesh K says:

    Hi,

    I have a question about Customizing Ribbon Control in outlook Explorer.

    I have added AdxRibbon tab, AdxRibbon Group and AdxRibbon Button and set the below property

    For ADXRibbonTab :
    Ribbon : OutlookExplorer
    Visible : true

    For ADXRibbonButton

    Image : 0
    ImageList : SomeImage1
    Ribbons : OutlookExplorer
    Size : Large
    Visible : True.

    When i am starting outlook, i am getting only ribbon menu along with outlook file menu.

    How do i show all the outlook menus along with my own ADXRibbonTab,ADXRibbonGroup,ADXRibbonButton at runtime.

    Thanks in Advance
    Ramesh K

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

    Hi Ramesh,

    Try to set the StartFromScratch property of your add-in module to (None).

  • Emanuel P. says:

    Hi,

    is there any way to not wrap the “Large Button” button text? As you can see in your examples, “Large” is on one line and “Button” on another line. How can we make them to be on a single line?

    Thanks a lot,
    Emanuel

  • Ty Anderson says:

    Hi Emanuel

    Unfortunately, the API does not provide a method to control the wrapping of the Label property.

    Ty

  • Gary says:

    very interesting, I am looking for a way rather than have a button that performs a task (runs a macro) to show as an indicator. for example red / green traffic light which shows red, until a specific e-mail has been received. Then all I require to do it have a quick glance at the ribbon rather than troll through e-mails. I am guessing I would need two buttons, one for the red traffic light always shown, then a second which sits on top, the green, when it receives a trigger off the back of a rule. Is this my best approach or can you think of another method. Many thanks G.

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

    Hello Gary,

    You can have a single button showing different images depending on your add-in’s logic. To modify the image, just set it to the corresponding property when required. Say, you can change ADXRibbonButton.Image thus referring to another index in the ImageList specified in ADXRibbonButton.ImageList. Or, since ImageList cuts out the alpha channel, you can set a new image to the ADXRibbonButton.Glyph property.

  • Gary says:

    Thanks Andrei, will play around and see what I can do.

  • Vaibhav says:

    Hi Gary,
    I want to add a border around a box containing buttons in my custom ribbon UI, just like there is one around the ‘Send’ Button. How is it possible? Is it even possible to do so?

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

    Hello Vaibhav,

    The Office Ribbon API doesn’t provide a way to achieve this.

Post a comment

Have any questions? Ask us right now!