Today's Guest Writer: Savraj Dhanjal

Savraj is a Program Manager on the Office User Experience team focused on user interface extensibility for Office developers.

This week, we'll look at the different types of buttons you can create with RibbonX. The Ribbon is a two-dimensional UI space, and as you can see from our built-in groups, there's a fair amount of variety in controls and control arrangement. The extensibility model exposes much of the richness and flexibility available in the different Ribbon control types, and buttons are no exception. I've included some code snippets that you can paste inside the following wrapper, to get valid customUI markup.

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">
  <ribbon>
    <tabs>
      <tab idMso="TabAddins">
        <!-- insert snippet here -->
      </tab>
    </tabs>
  </ribbon>
</customUI>

"It's just Buttons"

Ribbon extensibility, at its core, is about how developers can make a custom button show up in the Ribbon. Profound, isn't it? :) Anyway, A button can be small or large, and it can show or hide its label. It can also have a tooltip or a super tooltip. Like all custom controls in RibbonX that have images, you can copy the image for this button from a built-in control, using the imageMso property.


Four custom buttons. Each button snags its image from a built-in control.

<group id="myGroup" label="My Group">
  
  <button id="b1" imageMso="WebInsertHyperlink"
    size="large" label="Surf the Net" onAction="surf"/>
  
  <button id="b2" imageMso="HappyFace"
   
label="Smile" onAction="smile"/>

  <button id="b3" imageMso="FormatPainter" label="Paint"
    onAction="paint"/>

  <button id="b4" imageMso="AutoFilter" label="Filter"
   
onAction="filter"/>

</group>

You can also hide the labels on built-in buttons, so you get small 16x16 icons that appear quite like the icons on toolbars in non-Ribbon applications. Large buttons images are 32x32 pixels.


Hiding labels with the showLabel property.

<group id="myGroup" label="My Group">

  <button id="b1" imageMso="WebInsertHyperlink"
    size="large" label="Surf the Net" onAction="surf"/>

  <button id="b2" imageMso="HappyFace"
    showLabel="false" label="Smile" onAction="smile"/>

  <button id="b3" imageMso="FormatPainter"
    showLabel="false" label="Paint" onAction="paint"/>

  <button id="b4" imageMso="AutoFilter"
    showLabel="false" label="Filter" onAction="filter"/>

</group>

ToggleButtons

The canonical example of a toggleButton is the Bold button. You can create your own toggleButtons, and you can make them behave just like the bold button by writing callbacks. By tweaking the XML from the first example, we get a pair of toggleButtons.


ToggleButtons stay down when you click them.

<group id="myGroup" label="My Group">

  <toggleButton id="b1" imageMso="WebInsertHyperlink"
    size="large" label="Surf the Net" onAction="surf"/>

  <button id="b2" imageMso="HappyFace"
    showLabel="false" label="Smile" onAction="smile"/>

  <toggleButton id="b3" imageMso="FormatPainter"
    showLabel="false" label="Paint" onAction="paint"/>

  <button id="b4" imageMso="AutoFilter"
    showLabel="false" label="Filter" onAction="filter"/>

</group>

SplitButtons

SplitButtons combine the wonders of a one-click button with a set of choices in a menu. Here's a splitButton that I've placed in the Ribbon, using our existing button images.


Left: Hovering the button-half of a splitButton.
Right: Dropping the menu-half of a splitButton.

<group id="myGroup" label="My Group">

  <splitButton id="mySplit" size="large">

    <button id="b1" imageMso="WebInsertHyperlink"
      label="Surf the Net" onAction="surf"/>

    <menu id="splitMenu" itemSize="large">

      <button id="b2" imageMso="HappyFace" label="Smile"
       
onAction="smile" description="View pages about smiles."/>

      <button id="b3" imageMso="FormatPainter" label="Paint"
        onAction="paint" description="Learn to paint
        your house."/>

      <button id="b4" imageMso="AutoFilter" label="Filter"
       
onAction="filter" description="Read about water
        purification."/>
 
    </menu>
  </splitButton>
</group>

There are a few interesting things going on in the image above. First, you might notice that the menu items are large, and each item is displaying its description. You get this visual when you set your menu's itemSize to large -- we call this a "rich menu." You'll also notice that the HappyFace icon is a bit blurry. Wondering why? We didn't create, for Office 2007, a 32x32 version of this icon, because none of the applications use it. Office is scaling up the built-in 16x16 icon. (We could probably write a separate blog entry about the origins of the built-in HappyFace icon.) By the same token, if your add-in only has a large icon, and it needs to display the icon on a small button, Office will scale it down.

Button Arrangement

So you can have big and small buttons, and you can set properties like visibility, enabled state, and the label dynamically. What else can you do? Well you've probably noticed the fancy runs of buttons on some of the tabs in the Ribbon applications. You can create your own buttonGroups in RibbonX as well. Just wrap your buttons in this tag, and you get that neat visual style, a throwback to the days of toolbars. For the example below I also grabbed a couple built-in Office controls, using idMso, and these buttons work as you would expect.


Matching the toolbar-esque visual style. The last six buttons are in buttonGroups.

<group id="myGroup" label="My Group">

  <button id="r1" label="Vanilla Button" imageMso="Cut" />

  <buttonGroup id="myBGroup">
    <button id="b1" imageMso="WebInsertHyperlink"
     
label="Surf the Net" onAction="surf"/>

    <button id="b2" imageMso="HappyFace" label="Smile"
      onAction="smile" />
  </buttonGroup>

  <buttonGroup id="myBGroup2">
    <button id="b3" imageMso="FormatPainter" label="Paint"
      showLabel="false" onAction="paint" />

    <toggleButton idMso="Bold"/>
    
    <button id="b4" imageMso="AutoFilter" label="Filter"
      showLabel="false" onAction="filter" />
   
    <toggleButton idMso="Italic"/>
  </buttonGroup>

</group>

Custom Button Images

If you're an icon buff, you'll be excited to know that RibbonX now supports icon images with 32-bits -- 8 bits for red, green, and blue, and 8 bits for an alpha (transparency) channel. The "M" below is a 24-bit PNG with transparency. The soft edge of the shadow is preserved, thanks to the alpha channel. When you hover over the buttons, or when you click on them, you get all of the visual effects of the Ribbon for free.


Custom button with alpha channel.

<group id="myGroup" label="My Group">
  <button id="M" size="large" label="The M Button" 
    getImage="getM"/>
</group>

In the sample above, my C# callback, getM, grabs the PNG file, converts it to an IPictureDisp, and returns it to Office. In CommandBars, transparency was governed by the mask property -- which allowed to you "mask off" pixels in your button's picture property. Before picture and mask, we had copyFace and pasteFace, which are currently deprecated, because calls to these functions overwrite the user's clipboard.

So that's a quick preview of a few things you can do with buttons in the Ribbon. Stay posted for more exciting control types.