RibbonX Control Type Tour, Part 3

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 take a look at the gallery control. It's one of the most important controls in the new Office 2007 user experience, and we've exposed a good chunk of core gallery functionality for you to use in your own Office-based solutions.

As you may have read in the many blog postings already written about galleries, the purpose of a gallery is to roll up features which would have taken many clicks into a gallery of choices that lets you get the same result in just one click.

In the example add-in I'm going to show, I've mocked up a gallery that allows you to insert pictures in one click, instead of opening a dialog, navigating the file tree, and selecting an image. I've dropped this gallery on the Insert tab in Word after the Illustrations group, because that's where it fits in best with the surrounding features.

The nature photos gallery, courtesy RibbonX
(Click to enlarge)

 <gallery id="nature" 
    label="Nature Photos"
    size="large"
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    showItemLabel="false"/>

The anchor for a gallery is similar to that of a menu in that it can be small or large. In this case, I'm using a large, built-in film strip icon, with the imageMso attribute. As I've previously written, our controls use callbacks to specify dynamic properties like labels, and in some cases, the content of the control. The gallery control asks callbacks for the items that populate the gallery, unless the gallery contains statically declared items. In my example above, a callback returns 150x150 pixel PNG images converted to an IPictureDisp for each item.

One of the neat features of our gallery control is that it can automatically scale your images. The original PNG images used in my example are 150 pixels square. By specifying a new itemHeight and itemWidth the gallery will resize the images. I also changed the return value of my getItemCount callback to return sixteen items instead of nine. The gallery creates a 4x4 grid for a group of sixteen items.

Sixteen items and smaller images
(Click to enlarge)

 <gallery id="nature"
    label="Nature Photos"
    size="large"
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    itemHeight="75"
    itemWidth="75"
    showItemLabel="false"/>

You can also scale up images, of course. In the next example, the gallery is enlarging the 150-pixel square images to 200-pixel square images. The gallery control can also resize images without preserving the aspect ratio of the original image, but because it doesn't look great I didn't include a screenshot. :)

You can also specify the number of rows and columns the gallery should display. In this case, I've got just one column and two rows.

Scaling up images, setting rows and columns
(Click to enlarge)

 <gallery id="nature"
    label="Nature Photos" 
    size="large" imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    itemHeight="200"
    itemWidth="200"
    rows="2"
    columns="1"
    showItemLabel="false"/>

You can also choose to display labels on gallery items. The example below contains labels for each item, resizes the images to be much smaller, and is set to show ten rows.

Showing labels on gallery items
(Click to enlarge)

 <gallery id="nature"
    label="Nature Photos"
    size="large"
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    itemHeight="20"
    itemWidth="20"
    rows="10"
    columns="1"
    showItemLabel="true"/>

Just like in many of the built-in galleries it Office 2007, you can also add buttons to the bottom of a gallery. Typically these buttons would configure what appears in the gallery or open a related settings dialog box.

Buttons at the bottom
(Click to enlarge)

 <gallery id="nature"
    label="Nature Photos"
    size="large" 
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    rows="2"
    columns="2"
    showItemLabel="false">
    
    <button id="b222"
      imageMso="Save"
      label="Save selection to Nature Photos Server..."/>
    
    <button id="b229"
      imageMso="Dollar"
      label="Purchase more photos..."/>




</gallery>

That's the high-level overview of the functionality provided by the gallery control. We can't wait to see how you'll use it in the solutions you create!