RibbonX Control Type Tour, Part 1


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 16×16 icons that appear quite like the icons on toolbars in non-Ribbon applications. Large buttons images are 32×32 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 32×32 version of this icon, because none of the applications use it. Office is scaling up the built-in 16×16 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.

Comments (17)

  1. Alrik says:

    Thanks! I´ve been waiting for this info. I think this is a great way of defining the content of the Ribbon. Nice work!

  2. marlon says:

    Totally unrelated; forgive me.

    Mr. Harris, since the Word blog is not being updated, why not have someone from that team post  here every week (or two weeks)?

  3. Joseph says:

    Nice post. Is there a list of built-in icon IDs available anywhere?

    Thanks

  4. Keeron says:

    The list of IDs for the build-in controls as well as images is in the ‘customizing Office UI with RibbonX" document (its on the beta/connect website). Hopefully with Beta 2, its published online so anyone can access it.

  5. Nidonocu says:

    I think we need a post dedicated to the strange things that are in office like the HappyFace and bowling ball, oh.. and the Word pinball machine and Excel moonscape.. who knows what’s getting hidden in 2007? 😉

  6. Jon says:

    I apologize if this is the wrong place for this, but it’s somewhat related. Is there any blogs on the Office system and it’s programability? I’m interested in what’s new with the macros and VBA and such.

    Thanks and keep up the good work.

  7. Abigail says:

    Jon,

    Here’s one on Outlook Extensibility. He may know more.

    http://blogs.msdn.com/rgregg/

  8. sw says:

    It seems like Mozilla did it first with XUL.

  9. Mike Dunn says:

    Yes, and XUL overlays work quite well in FF. I like that O12 is doing something similar.

  10. Molly C says:

    > It seems like Mozilla did it first with XUL.

    And if so, Microsoft has no business adding similar functionality to Office and should be ridiculed for doing so.  /sarcasm /face_rollseyes

  11. Atamido says:

    I’m curious why they didn’t reuse the already designed and tested XUL that Mozilla produced.  I doubt it would cover all scenarios, but it would seem like a suitable starting point.

    At the very least, using XHTML for the pre-existing elements would probably be a good choice.  Starting out from scratch to produce a completely new method is not only redundant, but wasteful of developer’s time and resources.  Every new system has a learning curve, so using a pre-existing system would help everyone.

  12. Today’s Guest Writer: Savraj Dhanjal
    Savraj is a Program Manager on the Office User Experience team focused…