Andrew Whitechapel : Ribbon

Add-ins for Multiple Office Versions without PIAs

andreww — Tue, 03 Jun 2008 19:47:00 GMT

In a previous post, I discussed how you could build an add-in for multiple versions of Office, and explained the problems in this approach (and why it is not officially supported). One of the reasons this is not supported is because you end up building an add-in which has dependencies on a later version of the Office PIAs, even though your add-in is sometimes deployed to a machine with an earlier version of Office. The canonical example is where you build an add-in that conditionally uses both Office 2003 (and earlier) CommandBar technology and Office 2007 (and later) Ribbon and task pane technologies, as described in my earlier post. This add-in would normally have a dependency on the Office 2007 PIAs (where the IRibbonExtensibility and ICustomTaskPaneConsumer types are declared). When deployed to an Office 2007 machine, all is good, because the Office 2007 PIAs are present. However, when deployed to an Office 2003 machine – even though the Ribbon and task pane functionality is not used, it is still in the add-in code, and therefore still requires the Office 2007 PIAs. Is there a way around this problem?

Of course, one solution is to deploy the Office 2007 PIAs to the machine with Office 2003, but you then have the follow-on problems of registering multiple versions of the PIAs, and of loading the Office 2007 PIAs into an Office 2003 process. Not good.

Another way around this problem is to remove the dependency on the later PIAs. Because of the high degree of backwards compatibility in Office, you can safely assume that if your add-in works on Office 2003 (with the Office 2003 PIAs), then it should also work on Office 2007 (with the Office 2007 PIAs). So, the only issue is how to get it to work on an Office 2003 machine with only the Office 2003 PIAs present, even though your code uses types such as IRibbonExtensibility that are not present in Office 2003 or the Office 2003 PIAs. So, the question becomes, How can you write a solution which uses types defined in an assembly (the Office 2007 PIA) that is not referenced by the solution?

The answer, of course, is ComImport. For documentation on ComImport, see here and here. PIAs, and interop assemblies generally, can be created by using the Tlbimp.exe utility, which reads a type library and outputs an interop assembly, containing metadata that is the managed equivalent of the COM typelib. ComImport is a pseudo-custom attribute that indicates that a type has been defined in a previously published type library. You can apply this attribute when you want to generate interop metadata manually in source code that simulates the metadata produced by Tlbimp.exe.

Here’s an example. Note that I’m declaring an inner namespace “Office”, so that I can refer to the task pane and Ribbon types as if they were declared in the same namespace as the real Office types – that is, assuming the standard using statement with an alias, eg: using Office = Microsoft.Office.Core;.

Taking custom task panes first, note that ICustomTaskPaneConsumer has a member that takes an ICTPFactory object as a parameter. I therefore have to define ICTPFactory as well. ICTPFactory in turn has a member that takes a CustomTaskPane object, and this derives from _CustomTaskPane, so I need to define these two interfaces also. With Ribbons, the IRibbonExtensibility interface is straightforward, but the signatures of the callback methods that I must define for Office to use for my Ribbon controls tend to take IRibbonControl objects as parameters, so I need to define this interface also.

namespace MyOffice2003AddIn

{

namespace Office

{

#region Custom Task Pane

public enum MsoCTPDockPosition

{

msoCTPDockPositionLeft,

msoCTPDockPositionTop,

msoCTPDockPositionRight,

msoCTPDockPositionBottom,

msoCTPDockPositionFloating

}

public enum MsoCTPDockPositionRestrict

{

msoCTPDockPositionRestrictNone,

msoCTPDockPositionRestrictNoChange,

msoCTPDockPositionRestrictNoHorizontal,

msoCTPDockPositionRestrictNoVertical

}

[ComImport, Guid("000C033B-0000-0000-C000-000000000046"), TypeLibType((short)0x10c0), DefaultMember("Title")]

public interface _CustomTaskPane

{

[DispId(0)]

string Title { [return: MarshalAs(UnmanagedType.BStr)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(0)] get; }

[DispId(1)]

object Application { [return: MarshalAs(UnmanagedType.IDispatch)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)] get; }

[DispId(2)]

object Window { [return: MarshalAs(UnmanagedType.IDispatch)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(2)] get; }

[DispId(3)]

bool Visible { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(3)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(3)] set; }

[DispId(4)]

object ContentControl { [return: MarshalAs(UnmanagedType.IDispatch)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(4)] get; }

[DispId(5)]

int Height { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(5)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(5)] set; }

[DispId(6)]

int Width { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(6)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(6)] set; }

[DispId(7)]

MsoCTPDockPosition DockPosition { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(7)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(7)] set; }

[DispId(8)]

MsoCTPDockPositionRestrict DockPositionRestrict { [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(8)] get; [param: In] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(8)] set; }

[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(9)]

void Delete();

}

[ComImport, Guid("000C033B-0000-0000-C000-000000000046")]

public interface CustomTaskPane : _CustomTaskPane

{

}

[ComImport, Guid("000C033D-0000-0000-C000-000000000046"), TypeLibType((short)0x10c0)]

public interface ICTPFactory

{

[return: MarshalAs(UnmanagedType.Interface)]

[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)]

CustomTaskPane CreateCTP([In, MarshalAs(UnmanagedType.BStr)] string CTPAxID, [In, MarshalAs(UnmanagedType.BStr)] string CTPTitle, [In, Optional, MarshalAs(UnmanagedType.Struct)] object CTPParentWindow);

}

[ComImport, Guid("000C033E-0000-0000-C000-000000000046"), TypeLibType((short)0x10c0)]

public interface ICustomTaskPaneConsumer

{

[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)]

void CTPFactoryAvailable([In, MarshalAs(UnmanagedType.Interface)] ICTPFactory CTPFactoryInst);

}

#endregion

#region Ribbon

[ComImport, Guid("000C0396-0000-0000-C000-000000000046"), TypeLibType((short)0x1040)]

public interface IRibbonExtensibility

{

[return: MarshalAs(UnmanagedType.BStr)]

[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)]

string GetCustomUI([In, MarshalAs(UnmanagedType.BStr)] string RibbonID);

}

[ComImport, Guid("000C0395-0000-0000-C000-000000000046"), TypeLibType((short)0x1040)]

public interface IRibbonControl

{

[DispId(1)]

string Id { [return: MarshalAs(UnmanagedType.BStr)] [MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime), DispId(1)] get; }

}

#endregion

}

How do I arrive at these ComImport declarations? One way is to use the ildasm.exe utility to read the Office 2007 PIA (that is, Office.dll) to get the metadata, although this approach requires you to do further work to massage the metadata into the appropriate code definitions. Another way is to use Lutz Roeder’s Reflector, and this approach pretty much provides you the code definitions without any further work. It should go without saying that it is essential to get the correct GUIDs on each of the types.

With these interface type definitions in place, I can use normal expressions in my add-in code to implement custom task panes and Ribbons. For example, I can implement ICustomTaskPaneConsumer like this:

public class TaskPaneImpl : Office.ICustomTaskPaneConsumer

{

private Office.ICTPFactory ctpFactory;

internal Office.CustomTaskPane ctp;

public void CTPFactoryAvailable(Office.ICTPFactory CTPFactoryInst)

{

try

{

ctpFactory = CTPFactoryInst;

ctp = ctpFactory.CreateCTP(

"MyOffice2003AddIn.SimpleControl",

"SimpleControl", Type.Missing);

}

catch (Exception ex)

{

MessageBox.Show(ex.ToString());

}

...and I can implement IRibbonExtensibility as shown below. Note that I have to add the Ribbon customization code manually – because this is an Office 2003 add-in, and Visual Studio won’t allow me to add a wizard-generated Ribbon item to an Office 2003 project. This code assumes I have a simple RibbonX.xml resource which defines one ToggleButton.

[ComVisible(true)]

public class RibbonX : Office.IRibbonExtensibility

{

public string GetCustomUI(string ribbonID)

{

return Properties.Resources.RibbonX;

}

public void OnToggleTaskPane(

Office.IRibbonControl control, bool isPressed)

{

Globals.ThisAddIn._taskPane.ctp.Visible = isPressed;

}

..and then I can use these implementations in my add-in like this:

public partial class ThisAddIn

{

internal TaskPaneImpl _taskPane;

private RibbonX _ribbon;

protected override object RequestService(Guid serviceGuid)

{

if (serviceGuid == typeof(Office.ICustomTaskPaneConsumer).GUID)

{

if (_taskPane == null)

{

_taskPane = new TaskPaneImpl();

}

return _taskPane;

}

else if (serviceGuid == typeof(Office.IRibbonExtensibility).GUID)

{

if (_ribbon == null)

{

_ribbon = new RibbonX();

}

return _ribbon;

}

return base.RequestService(serviceGuid);

}

Using this approach means that I no longer need to reference the Office 2007 PIAs in my add-in, which allows my add-in to work on an Office 2003 machine as well as on an Office 2007 machine, without having to deploy Office 2007 PIAs to the Office 2003 machine.

Ribbon and Task Pane in Access Add-ins

andreww — Thu, 22 May 2008 19:38:00 GMT

In an earlier post, I looked at how you could morph a VSTO project for one application into a project for another application – specifically, how you could build a VSTO add-in for Access. Note that this is explicitly not supported. However, although this was only intended as an investigative exercise, I notice that some people have added comments to the post asking for further information about things like custom Ribbons. So, to continue the investigative exercise, I’ll look today at how you could build on a VSTO Access add-in to implement custom task panes and Ribbons. The following discussion builds on the Access add-in I discussed in the earlier post.

Recall that you have two options for building custom task panes and Ribbons: you can use the low-level approach of implementing the interfaces directly; or you can use the VSTO wrapper classes and designer support. Let’s look at both options. Many moons ago, I introduced the VSTO low-level support in a blog post, and the updated documentation for the technique is here. Documentation on the VSTO CustomTaskPane wrappers and Ribbon designer are here and here.

To build a custom task pane (regardless of whether or not I use the VSTO wrappers), I must first set up a custom UserControl of some kind (which I’ll call SimpleControl). Then, for the low-level approach, I need to write a class that implements ICustomTaskPaneConsumer. In the CTPFactoryAvailable method, I’ll simply cache the ICTPFactory object for later use, eg:

public class TaskPaneHelper : ICustomTaskPaneConsumer

{

internal ICTPFactory taskPaneFactory;

public void CTPFactoryAvailable(ICTPFactory CTPFactoryInst)

{

taskPaneFactory = CTPFactoryInst;

}

In my ThisAddIn class, I declare a couple of fields: one for this helper class, and one for the Office CustomTaskPane PIA object:

private TaskPaneHelper taskPaneHelper;

internal Office.CustomTaskPane taskPane;

Then, I must override the RequestService virtual method to return an instance of my helper class:

protected override object RequestService(Guid serviceGuid)

{

if (serviceGuid == typeof(Office.ICustomTaskPaneConsumer).GUID)

{

if (taskPaneHelper == null)

{

taskPaneHelper = new TaskPaneHelper();

}

return taskPaneHelper;

}

return base.RequestService(serviceGuid);

}

Finally, add code to my ThisAddIn_Startup method to instantiate the task pane:

private void ThisAddIn_Startup(object sender, System.EventArgs e)

{

if (taskPaneHelper.taskPaneFactory != null)

{

taskPane = taskPaneHelper.taskPaneFactory.CreateCTP(

"MyAccessAddIn.SimpleControl", "Contoso", Type.Missing);

}

Next, the Ribbon. In the Solution Explorer, I can right-click on the project and select Add New Item. From the New Item dialog, I select a Ribbon XML item (not the Ribbon Visual Designer item), and name the new class RibbonX. This generates some code in RibbonX.cs and some Ribbon XML. I follow the generated comments to move the override of CreateRibbonExtensibilityObject into the ThisAddIn class. Then, I’ll modify the RibbonX.xml to give me one ToggleButton:

<?xml version="1.0" encoding="UTF-8"?>

<tabs>

<toggleButton id="toggleTaskPane"

onAction="toggleTaskPane_OnAction"

label="TaskPane"

imageMso="ControlLayoutStacked"

size="large" />

</group>

</tab>

</tabs>

</ribbon>

</customUI>

Note: I used the ImageMso RibbonIDs VSTO Power Tool to get the imageMso value.

In my RibbonX class, I implement the button onAction handler to toggle the visibility of the custom task pane:

public void toggleTaskPane_OnAction(Office.IRibbonControl control, bool isPressed)

{

Globals.ThisAddIn.taskPane.Visible = isPressed;

}

That’s it. I can now press F5 to test-run my prototype.

Now that I’ve looked at how to do this using the low-level support, I’ll look at the alternative approach of using the VSTO wrappers and designers. First the custom task pane. If I’m using the VSTO wrappers, I can delete the TaskPaneHelper class altogether, including the TaskPaneHelper field in the ThisAddIn class, the override for RequestService and the code I previously added to ThisAddIn_Startup. I also need to change the type of my taskPane field from the Office PIA type to the wrapped VSTO type:

//internal Office.CustomTaskPane taskPane;

internal Microsoft.Office.Tools.CustomTaskPane taskPane;

The only other thing I need to do is to use the VSTO CustomTaskPanes collection object in my ThisAddIn_Startup method:

private void ThisAddIn_Startup(object sender, System.EventArgs e)

{

//if (taskPaneHelper.taskPaneFactory != null)

//{

// taskPane = taskPaneHelper.taskPaneFactory.CreateCTP(

// "Word2AccessAddIn.SimpleControl", "Contoso", Type.Missing);

//}

taskPane = this.CustomTaskPanes.Add(new SimpleControl(), "Contoso");

}

F5 again, and this should behave exactly as before.

Next, the Visual Ribbon designer. I can delete the previously-generated RibbonX.cs and RibbonX.xml, and the override for CreateRibbonExtensibilityObject. Instead, I’ll add another new item – this time, a Ribbon Visual Designer item, and I’ll name the class VisualRibbon. I can use the designer to put a ToggleButton on the custom tab, and set its properties (including using the same ImageMso RibbonIDs power tool for the OfficeImageId property).

The one slight anomaly is that I need to set the RibbonType property of the custom Ribbon to a string that matches the string that the host application will pass in when it calls the IRibbonExtensibility.GetCustomUI method. Previously, when I used the low-level support, this was irrelevant, because it is not actually used in the code anywhere. However, this value is used by Outlook because Outlook supports multiple custom Ribbons for multiple message classes. For this reason, the VSTO Ribbon Visual Designer allows you to set this property, and offers a dropdown list of the known valid property values. These include values such as “Microsoft.Excel.Workbook”, “Microsoft.Outlook.Appointment”, etc. Of course, there is no VSTO Access support, so the dropdown list does not include the value that Access will pass in. Access will pass in the value “Microsoft.Access.Database” – so you need to set this value manually in the code (in the VisualRibbon.Designer.cs, which contains the InitializeComponent method and other methods in the hidden part of the partial class):

this.RibbonType = "Microsoft.Access.Database";

Finally, I can implement the Click handler for my new ToggleButton to behave in the same way as in my low-level implementation:

private void toggleButton1_Click(object sender, RibbonControlEventArgs e)

{

Globals.ThisAddIn.taskPane.Visible =

((Microsoft.Office.Tools.Ribbon.RibbonToggleButton)sender).Checked;

}

That’s it – F5 to test.

As before, note that this is not a supported scenario: there are 2 reasons for this post. The first reason is to explore the possibilities off the beaten track of officially documented features in VSTO – purely in the interests of scientific curiosity. The second reason is to make an important point about the strategic design of VSTO add-ins. We’re very careful to build our tooling and runtime support in such a way that it does not block support for potential additional hosts. As I’ve shown, there’s nothing in the VSTO add-in class, the VSTO custom task pane wrappers, or the VSTO ribbon wrappers and designers that prevents their use with host applications that are not (yet) supported – even host applications that themselves do not yet support task panes or ribbons.

Preserving the alpha channel when converting images

andreww — Thu, 11 Oct 2007 00:37:00 GMT

Here is a guest post by Eric Faller, Ribbon developer guru and all-round nice guy. It's a follow-up to my post about converting between the image formats used by Office and the .NET framework.

I’ll be talking about handling the alpha channel (transparency) of the images, mentioned at the end of that post and in the comments. I’d recommend reading that post first in order to get up to speed on the IPictureDisp interface and some of the other concepts we’ll be discussing.

I’d also recommend reading the RibbonX Image FAQ on Jensen Harris’ blog. It has a lengthy discussion about the different formats Office has used for image transparency in the past, as well as some common pitfalls when loading images into Office. In this post I’ll be talking about getting images out of Office, but many of the problems will be similar (DDB vs DIB, etc.).

Office 2007 introduces a new API for fetching icon images, the GetImageMso function on the CommandBars object. It takes the ID of a Ribbon control and returns its icon in IPictureDisp format. You can use one of the many methods discussed in Andrew’s previous post to convert these objects into .NET-friendly System.Drawing.Bitmap objects.

If you do, you might notice that the icons don’t look exactly correct when you draw them – the transparent edges show up white and shadow elements look black. For example here’s what the “Paste” icon looks like if drawn on a WinForm:

If you’re only using the smaller versions of the icons (16x16), drawing them on a white background, and don’t care too deeply about pixel-perfect visuals, you might be OK with this. Calling Bitmap.MakeTransparent on the icon will help get rid of the white border, but it’s still not quite perfect.

The bad news is that if you want to stick with purely .NET code, you’re stuck with this – that’s the best that your icon can look. The problem is that the alpha channel has already been lost during the conversion from IPictureDisp to System.Drawing.Bitmap.

The CLR and GDI+ internally call Win32 GDI functions during the conversion, and these functions are not alpha channel-aware. GDI itself was written long before alpha channels became popular, and as a result almost all of the standard Win32 GDI functions will ignore the alpha channel and appear to “throw it away” during various copy and conversion operations. Alpha channel support was only added with the AlphaBlend function in Windows 98/2000 with the addition of MSIMG32.DLL.

The good news is that we can get a lot better transparency in our images if we’re willing to do a little native code interop and call AlphaBlend ourselves. It’s slightly complicated, so I’ll just show you the code and then explain it. Here’s a function that will convert an IPictureDisp object to a System.Drawing.Bitmap object, using the AlphaBlend function:

public static Bitmap ConvertWithAlphaBlend(IPictureDisp ipd)

{

// get the info about the HBITMAP inside the IPictureDisp

DIBSECTION dibsection = new DIBSECTION();

GetObjectDIBSection((IntPtr)ipd.Handle, Marshal.SizeOf(dibsection), ref dibsection);

int width = dibsection.dsBm.bmWidth;

int height = dibsection.dsBm.bmHeight;

// zero out the RGB values for all pixels with A == 0

// (AlphaBlend expects them to all be zero)

unsafe

{

RGBQUAD* pBits = (RGBQUAD*)(void*)dibsection.dsBm.bmBits;

for (int x = 0; x < dibsection.dsBmih.biWidth; x++)

for (int y = 0; y < dibsection.dsBmih.biHeight; y++)

{

int offset = y * dibsection.dsBmih.biWidth + x;

if (pBits[offset].rgbReserved == 0)

{

pBits[offset].rgbRed = 0;

pBits[offset].rgbGreen = 0;

pBits[offset].rgbBlue = 0;

}

// create the destination Bitmap object

Bitmap bitmap = new Bitmap(width, height, PixelFormat.Format32bppArgb);

// get the HDCs and select the HBITMAP

Graphics graphics = Graphics.FromImage(bitmap);

IntPtr hdcDest = graphics.GetHdc();

IntPtr hdcSrc = CreateCompatibleDC(hdcDest);

IntPtr hobjOriginal = SelectObject(hdcSrc, (IntPtr)ipd.Handle);

// render the bitmap using AlphaBlend

BLENDFUNCTION blendfunction = new BLENDFUNCTION(AC_SRC_OVER, 0, 0xFF, AC_SRC_ALPHA);

AlphaBlend(hdcDest, 0, 0, width, height, hdcSrc, 0, 0, width, height, blendfunction);

// clean up

SelectObject(hdcSrc, hobjOriginal);

DeleteDC(hdcSrc);

graphics.ReleaseHdc(hdcDest);

graphics.Dispose();

return bitmap;

}

Except for the “unsafe” block, the code should be pretty straightforward if you’re a Win32 GDI programmer: we create a new blank 32-bit HDC from a Bitmap object, create a compatible HDC to select the IPictureDisp’s HBITMAP into, render it with AlphaBlend, and clean up.

Now we need to look at the pixel manipulations inside the “unsafe” block. If we leave that section out, this is what we would get:

This is better – the shadow inside if the icon doesn’t look as bad, but we still have the white border in the regions of the icon that are completely transparent.

The problem happens because of an ambiguity that occurs when a pixel is completely transparent. In this case the A (‘alpha’) component of the pixel is zero, but the R, G and B components of the pixel can be anything since they don’t show up. What actually happens with those values is dependent on the convention that you follow. Unfortunately, Office follows a different convention than the AlphaBlend function does. The AlphaBlend function expects the RGB values to all be zero if the A value is zero. Office leaves the R, G and B values all equal to 255, which creates the white color seen in the images above. It does this so that the transparent pixels don’t turn out black if the image is “compacted” by GDI+ or the CLR, leaving us with images that look like this by default, which is even worse than what we started with:

Fortunately we can convert between the two conventions for the completely transparent pixels by checking for zero A values and zeroing out the RGB values. It takes some unsafe code to do it, but it works. Here’s how it looks:

It looks a lot better, but if you look carefully, it’s still not perfect. The shadow has been “halftoned”: all of the alpha values have been rounded to either 0 or 255, making the shadow either completely transparent or completely black. We want a nice gray gradient shadow. It looks like the problem happens in the Bitmap object, when converting to and from the HDC. If you skip the intermediate Bitmap object and use the above code to draw directly to a Graphics object on a window, then it will render properly. I’ve played around with the PixelFormat, CompositingMode, and other parameters to the Graphics and Bitmap objects, but haven’t been able to make it work.

It looks like we’ll have to give up on using AlphaBlend and go down to the lowest level: pixel-by-pixel copying. Since we were already doing per-pixel processing in the previous function, the new one actually looks simpler:

public static Bitmap ConvertPixelByPixel(IPictureDisp ipd)

{

// get the info about the HBITMAP inside the IPictureDisp

DIBSECTION dibsection = new DIBSECTION();

GetObjectDIBSection((IntPtr)ipd.Handle, Marshal.SizeOf(dibsection), ref dibsection);

int width = dibsection.dsBm.bmWidth;

int height = dibsection.dsBm.bmHeight;

// create the destination Bitmap object

Bitmap bitmap = new Bitmap(width, height, PixelFormat.Format32bppArgb);

unsafe

{

// get a pointer to the raw bits

RGBQUAD* pBits = (RGBQUAD*)(void*)dibsection.dsBm.bmBits;

// copy each pixel manually

for (int x = 0; x < dibsection.dsBmih.biWidth; x++)

for (int y = 0; y < dibsection.dsBmih.biHeight; y++)

{

int offset = y * dibsection.dsBmih.biWidth + x;

if (pBits[offset].rgbReserved != 0)

{

bitmap.SetPixel(x, y, Color.FromArgb(pBits[offset].rgbReserved, pBits[offset].rgbRed, pBits[offset].rgbGreen, pBits[offset].rgbBlue));

}

return bitmap;

}

Here’s what the final pixel-perfect result looks like:

Converting between IPictureDisp and System.Drawing.Image

andreww — Tue, 31 Jul 2007 03:47:00 GMT

This is an interesting manifestation of the gap between COM-based native servers, such as the Office client apps, and managed code. There are a number of scenarios where you need to convert image formats between the native COM-based IPictureDisp and the managed System.Drawing.Image class and its derivatives such as Bitmap. One such scenario is in providing images for custom ribbons, including ribbon images used for Outlook custom form regions.

You have several choices for performing the conversion, depending on the direction of the conversion.

The "traditional" approach is to use the GetIPictureDispFromPicture and GetPictureFromIPicture methods in the System.Windows.Forms.AxHost class. These are both protected members of the class, so you can't use them externally. For this reason, it is common to subclass the AxHost class and expose public methods that internally call the base class protected methods. This approach allows you to convert in both directions:

internal class AxHostConverter : AxHost

{

private AxHostConverter() : base("") { }

static public stdole.IPictureDisp ImageToPictureDisp(Image image)

{

return (stdole.IPictureDisp)GetIPictureDispFromPicture(image);

}

static public Image PictureDispToImage(stdole.IPictureDisp pictureDisp)

{

return GetPictureFromIPicture(pictureDisp);

}

Note that this is a peripheral capability of the AxHost class – its main purpose is to act as a base class for derived classes that host native ActiveX controls in managed Windows.Forms controls. When you add an ActiveX control to a managed project, Visual Studio uses the aximp.exe tool to generate and compile a class derived from AxHost. For documentation, see here.

Your second option is to use OleLoadPicture or OleCreatePictureIndirect. Tom Quinn mentions this in his blog post here, and there's an old support article on the topic here. OleLoadPicture creates a new picture object and initializes it from the contents of a stream. This is equivalent to calling OleCreatePictureIndirect(NULL, ...) followed by IPersistStream::Load. You'll need to p/invoke to these native methods. As you can see from the managed declaration of OleCreatePictureIndirect below, it takes a particular struct type as its first parameter – so, you need to declare this struct type also. This method (and the real definition of the native struct) can accommodate multiple image formats, including bitmap, icon and metafile. The simplified example listed here only supports bitmap. The struct is only used when converting from an Image to an IPictureDisp – the reverse operation is simpler, being basically just a call to Image.FromHbitmap. For documentation, see here.

internal class OleCreateConverter

{

[DllImport("oleaut32.dll", EntryPoint = "OleCreatePictureIndirect",

CharSet = CharSet.Ansi, ExactSpelling = true, PreserveSig = true)]

private static extern int OleCreatePictureIndirect(

[In] PictDescBitmap pictdesc, ref Guid iid, bool fOwn,

[MarshalAs(UnmanagedType.Interface)] out object ppVoid);

const short _PictureTypeBitmap = 1;

[StructLayout(LayoutKind.Sequential)]

internal class PictDescBitmap

{

internal int cbSizeOfStruct = Marshal.SizeOf(typeof(PictDescBitmap));

internal int pictureType = _PictureTypeBitmap;

internal IntPtr hBitmap = IntPtr.Zero;

internal IntPtr hPalette = IntPtr.Zero;

internal int unused = 0;

internal PictDescBitmap(Bitmap bitmap)

{

this.hBitmap = bitmap.GetHbitmap();

}

public static stdole.IPictureDisp ImageToPictureDisp(Image image)

{

if (image == null || !(image is Bitmap))

{

return null;

}

PictDescBitmap pictDescBitmap = new PictDescBitmap((Bitmap)image);

object ppVoid = null;

Guid iPictureDispGuid = typeof(stdole.IPictureDisp).GUID;

OleCreatePictureIndirect(pictDescBitmap, ref iPictureDispGuid, true, out ppVoid);

stdole.IPictureDisp picture = (stdole.IPictureDisp)ppVoid;

return picture;

}

public static Image PictureDispToImage(stdole.IPictureDisp pictureDisp)

{

Image image = null;

if (pictureDisp != null && pictureDisp.Type == _PictureTypeBitmap)

{

IntPtr paletteHandle = new IntPtr(pictureDisp.hPal);

IntPtr bitmapHandle = new IntPtr(pictureDisp.Handle);

image = Image.FromHbitmap(bitmapHandle, paletteHandle);

}

return image;

}

Your third option is to use the VB6 compatibility library, documented here. To use this, you'll need to add a reference to Microsoft.VisualBasic.Compatibility.dll, which is listed on the .NET tab of the Add References dialog (it resides in the GAC). Then, you can use the ImageToIPictureDisp and IPictureDispToImage methods in the Support class. This is obviously by far the simplest approach, although it does pull in the VB6 compatibility DLL. Internally, the VB6 compatibility code looks a lot like the second option above – using OleCreatePictureIndirect.

using Microsoft.VisualBasic.Compatibility.VB6;

internal class VB6CompatibilityConverter

{

public static stdole.IPictureDisp ImageToPictureDisp(Image image)

{

return (stdole.IPictureDisp)Support.ImageToIPictureDisp(image);

}

public static Image PictureDispToImage(stdole.IPictureDisp pictureDisp)

{

return Support.IPictureDispToImage(pictureDisp);

}

Finally, you can implement IPictureDisp and IPicture yourself, documented here and here. This is fine if you just want to convert from an Image to an IPictureDisp, but doesn't help you converting in the other direction. The implementation below relies on the Image actually being a derived Bitmap type, because we call Bitmap.GetHbitmap internally. If you want to keep the support to the generic Image type, you'll have to do a lot more work to p/invoke to a bunch of undocumented GDI methods instead.

internal class PictureDispConverter

{

public static stdole.IPictureDisp BitmapToPictureDisp(Bitmap bitmap)

{

return new PictureDispImpl(bitmap);

}

public static Image PictureDispToBitmap(stdole.IPictureDisp pictureDisp)

{

// TODO

return null;

}

internal class PictureDispImpl : stdole.IPictureDisp, stdole.IPicture

{

#region Init

[DllImport("gdi32.dll")]

static extern void DeleteObject(IntPtr handle);

private Bitmap _image;

private IntPtr _handle;

public PictureDispImpl(Bitmap image)

{

_image = image;

}

~PictureDispImpl()

{

if (_handle != IntPtr.Zero)

{

DeleteObject(_handle);

}

#endregion

#region IPictureDisp Members

public int Width

{

get { return _image.Width; }

}

public int Height

{

get { return _image.Height; }

}

public short Type

{

get { return 1; }

}

public int Handle

{

get

{

if (_handle == IntPtr.Zero)

{

_handle = _image.GetHbitmap();

}

return _handle.ToInt32();

}

public int hPal

{

get { return 0; }

set { }

}

public void Render(

int hdc, int x, int y, int cx, int cy, int xSrc, int ySrc, int cxSrc, int cySrc, IntPtr prcWBounds)

{

Graphics graphics = Graphics.FromHdc(new IntPtr(hdc));

graphics.DrawImage(

_image, new Rectangle(x, y, cx, cy), xSrc, ySrc, cxSrc, cySrc, GraphicsUnit.Pixel);

}

#endregion

#region IPicture Members

public int Attributes

{

get { return 0; }

}

public int CurDC

{

get { return 0; }

}

public bool KeepOriginalFormat

{

get { return false; }

set { }

}

public void PictureChanged()

{

}

public void SaveAsFile(IntPtr pstm, bool fSaveMemCopy, out int pcbSize)

{

pcbSize = 0;

}

public void SelectPicture(int hdcIn, out int phdcOut, out int phbmpOut)

{

phdcOut = 0;

phbmpOut = 0;

}

public void SetHdc(int hdc)

{

}

#endregion

}

All of the methods and types described above are documented, so all of these approaches are valid. Obviously, you'll have to do some work to write the helper classes along the lines indicted above, and some require more work (and maintenance) than others, of course, but you have options to choose from.

The one thing that is missing from all the IPictureDisp-to-Image conversions is the handling of alpha channels. I haven't quite figured out how to preserve the alpha channel, although Eric assures me that some tinkering with AlphaBlend ought to work. I'll play with that another day.

Why is it so hard to shim IRibbonExtensibility?

andreww — Fri, 09 Mar 2007 22:35:00 GMT

The COM Shim Wizards are a set of Visual Studio 2005 project wizards that automate the generation of COM shims for non-VSTO managed Office extensions. These shims support COM add-ins, smart tags and real-time data components. The shim for each is broadly similar, although there are obvious differences to allow for the different interfaces that each component implements, registration differences and so on.

There have been many questions in the forums over the last few months as to why these shims do not support the new Office 2007 extensibility interfaces, particuarly the interfaces for custom ribbons, custom task panes, and custom form regions. The short answer is that the shims are written to support a specific set of interfaces (IDTExtensibility2, ISmartTagRecognizer, ISmartTagAction, IRtdServer), and would therefore need to be extended to support the new interfaces (IRibbonExtensibility, ICustomTaskPaneConsumer, FormRegionStartup, etc).

OK, so why don’t we update the shims to support these new interfaces? The answer is that for all the interfaces except IRibbonExtensibility, this would be fairly simple. The problem is IRibbonExtensibility.

First the good news. The good news is that Office is generally moving towards an extensibility model where all new interfaces are implementable via COM add-ins (managed or unmanaged). More good news: all of these new interfaces are accommodated by the VSTO runtime if you’re building VSTO add-ins. If you’re not building VSTO add-ins, you simply implement the interface in your add-in code directly (in fact, you can also do this in VSTO add-ins if you don’t want to use the higher-level VSTO abstractions). The COM shim can be easily extended to specifically support most of these interfaces.

Now the bad news: although all the interfaces are implementable by add-ins, they are not all the same. Specifically, the programming model is different. Most especially, the programming model for ribbon extensibility is completely different from all the other interfaces. All the other interfaces follow the same model as any traditional COM interface. That is, the interface defines a number of methods, which are the communication points (the “interface”) between Office and the add-in. IRibbonExtensibility does define such an interface (it is a COM interface, after all), but it also assumes additional methods that are not defined in the interface.

IRibbonExtensibility only defines one method (GetCustomUI), BUT Office will expect to call back on your IRibbonExtensibility object for any number of additional methods in response to user interaction with the ribbon and any programmatic ribbon control state changes. For example, in your ribbon XML, you would specify that the callback method for a button might be MyButtonCallbackMethod – and this method is clearly not defined in the IRibbonExtensibility interface. In other words, while IRibbonExtensibility is basically a COM interface, it is most emphatically an automation interface. That is, you’re allowed to define any number of additional methods on the end of the interface, and Office will call back on these methods using IDispatch::GetIDsOfNames and IDispatch::Invoke. So why is an automation interface a problem for the shim?

Recall that there are two standard ways to build a shim: containment and aggregation.

With containment, the shim acts like an outer component, and contains pointers to interfaces on the inner component (the add-in, smart tag, etc). The shim re-implements the same interfaces as the add-in, and when Office calls into the interface on the shim, the shim then passes the call on to the add-in’s implementation of the same interface. With this approach, the shim can specialize the interface with prolog and epilog code wrapping the call to the add-in. This is how the shim is currently written: it uses containment for the interface on the add-in. We do this because we want to provide behavior that is additional to the add-in’s implementation of the interface – notably to create and destroy appdomains as part of the startup (IDTExtensibility2::OnConnection) and shutdown (IDTExtensibility2::OnDisconnection) sequences. The same model holds true for smart tags and RTD components (although with different interfaces, of course).

We could extend the shim’s containment model to cover ICustomTaskPaneConsumer and FormRegionStartup. Unfortunately, we can’t extend it to cover IRibbonExtensibility, because Office relies on the additional methods in the ribbon object that are not defined in the IRibbonExtensibility interface. If we don’t know what these additional methods are, we can’t provide a containment for them.

Aggregation is a specialization of composition. When an outer component aggregates an interface of an inner component, it doesn't reimplement the interface - it merely passes the inner component's interface pointer directly to the caller. With this model, the outer component can't specialize the behavior of the inner component. The critical problem with aggregation is that you’re handing out an interface pointer to the inner object back out to the caller (Office in this case). Because of this, you must be very careful to construct the inner object so that it is aware that it is being aggregated. Why? Because of the COM rules of identity, and specifically QueryInterface transitivity.

A COM component can implement any number of interfaces, and a caller must be able to switch between these interfaces, and back again. The COM rules state that “the QueryInterface method takes an interface ID and returns the requested COM interface on the same object. The set of interface IDs accessible via QueryInterface is the same from every interface on the object.” That is, whatever COM interface pointer a caller has on an object, it should be able to switch to any other interface on that object, and back again. This is a problem in aggregation, because here the caller starts off with a pointer to the outer object’s interfaces, and later gets handed a pointer to the inner object’s interfaces. Now, the outer object is aware that it is aggregating an inner object, so it can always deal with QIs for inner object interfaces correctly. However, we can’t have the caller QI on an inner object interface directly, because the inner object doesn’t have any knowledge of the outer object’s interfaces.

So, how does aggregation work? The solution is for the inner object to delegate IUnknown calls in its own interfaces, but also allow the outer object to access the inner object's IUnknown functions directly. All in all, aggregation is reasonably well-understood, and it works. The critical issue is that the inner object needs to know that it is being aggregated, so that it can take the correct action when QI calls come in. This is simple enough if you’re building your inner object with ATL – by default, ATL objects are aggregatable as inner objects. It’s not so simple if you’re building your inner object with managed code. It's even more difficult if your inner object is managed and your outer object is unmanaged.

There is an additional problem in the shim/add-in scenario, because typically, you build an add-in and then use the COM shim wizards to generate a shim. While we can write wizards that generate shims, the wizard can’t interfere with the code in the add-in itself - you might not even have the sourcecode of the add-in. So, there’s no easy way for us to make the add-in behave correctly as an inner object in an aggregation.

So, where do we go from here?

One option that we considered was to extend the existing shim containment model to allow the shim to reflect over the add-in to discover what additional methods are exposed from the object that implements IRibbonExtensibility, and then shim those methods also. But that’s a lot of work at runtime, and potentially error-prone. We would have to assume that any public method on the object is a potential ribbon callback, and that’s a wild assumption. Or, we’d have to mandate that the add-in developer adds some [RibbonCallback] attribute to each of the methods they want to expose. But, the existing shim doesn’t make any such assumptions about the add-in, and we don’t want to touch the add-in code at all. So, this is not a viable option.

Another option that we considered early on was to override the InternalQueryInterface method on the shim (which, you may recall is implemented with ATL). The thinking here was that for any new extensibility interface QI'd by the calling host, we would delegate to the add-in itself:

HRESULT WINAPI CConnectProxy::InternalQueryInterface(

void* pThis, const _ATL_INTMAP_ENTRY* pEntries, REFIID iid, void** ppvObject)

{

if (m_pConnect &&

(iid == IID_ICustomTaskPaneConsumer

|| iid == IID_FormRegionStartup

|| iid == IID_IRibbonExtensibility

|| iid == IID_IBlogExtensibility

|| iid == IID_IBlogPictureExtensibility

|| iid == IID_IDocumentInspector

|| iid == IID_SignatureProvider

|| iid == IID_EncryptionProvider ))

{

HRESULT hr = m_pConnect->QueryInterface(iid, ppvObject);

if (hr == S_OK)

return hr;

}

return CComObjectRootBase::InternalQueryInterface(

pThis, pEntries, iid, ppvObject);

}

This could be simplified further, so that we QI on the inner object for any interface apart from the ones we want the shim itself to handle:

HRESULT WINAPI CConnectProxy::InternalQueryInterface(

void* pThis, const _ATL_INTMAP_ENTRY* pEntries, REFIID iid, void** ppvObject)

{

if (m_pConnect

&& iid != IID__IDTExtensibility2

&& iid != IID_IUnknown

&& iid != IID_IDispatch)

{

HRESULT hr = m_pConnect->QueryInterface(iid, ppvObject);

if (hr == S_OK)

return hr;

}

return CComObjectRootBase::InternalQueryInterface(

pThis, pEntries, iid, ppvObject);

}

BUT: this breaks COM identity rules, because in this approach we’re handing out a pointer to one of the new interfaces, which may be implemented in a separate object from the add-in. So, if Office were ever to QI again on that pointer, they would not get a QI closure to all the interfaces supported by the add-in. In other words, this code would implement a kind of partial or fake aggregation, without the most crucial feature of real aggregation.

It’s seductive to think that the following would work (recall that the COM map in an ATL project expands out to the QueryInterface implementation):

BEGIN_COM_MAP(CConnectProxy)

COM_INTERFACE_ENTRY(IDTExtensibility2)

COM_INTERFACE_ENTRY2(IDispatch, IDTExtensibility2)

COM_INTERFACE_ENTRY_AGGREGATE(IID_ICustomTaskPaneConsumer , m_pConnect)

COM_INTERFACE_ENTRY_AGGREGATE(IID_FormRegionStartup, m_pConnect)

COM_INTERFACE_ENTRY_AGGREGATE(IID_IRibbonExtensibility, m_pConnect)

COM_INTERFACE_ENTRY_AGGREGATE(IID_IBlogExtensibility, m_pConnect)

COM_INTERFACE_ENTRY_AGGREGATE(IID_IBlogPictureExtensibility, m_pConnect)

COM_INTERFACE_ENTRY_AGGREGATE(IID_IDocumentInspector, m_pConnect)

COM_INTERFACE_ENTRY_AGGREGATE(IID_SignatureProvider, m_pConnect)

COM_INTERFACE_ENTRY_AGGREGATE(IID_EncryptionProvider , m_pConnect)

END_COM_MAP()

…which could be simplified to:

BEGIN_COM_MAP(CConnectProxy)

COM_INTERFACE_ENTRY(IDTExtensibility2)

COM_INTERFACE_ENTRY2(IDispatch, IDTExtensibility2)

COM_INTERFACE_ENTRY_AGGREGATE_BLIND(m_pConnect)

END_COM_MAP()

In other words, fix up the COM map of the shim so that all calls to non-IDTExtensibility2 interface functions get passed on to the add-in. In fact, this probably would work, right now at least. However, if you think about it, this is really no different from the InternalQI override above – we’re still breaking the QI transitivity rule. We’re asserting that we aggregate the add-in as the inner object, when in fact we don’t aggregate it at all. The add-in object (or, realistically, the multiple add-in objects that implement each of the extensibility interfaces) are crucially unaware that we’re presenting them as being aggregated.

So, why do I say it would work for now? It seems that right now, Office gets the first interface pointer on the object (the IUnknown of the object that implements IDTExtensibility2), and then always uses that pointer to QI for any subsequent interfaces. Right now, it doesn't QI on any of the subsequent interfaces. In other words, the potential QI transitivity breach of these two approaches is not in fact being hit – but there’s no guarantee that this would always be the behavior, and both approaches are technically still wrong, so it’s obviously an unacceptable risk.

The correct solution is to either (a) truly aggregate the add-in and all its inner objects, or (b) extend the existing shim containment model to cover all 7 of the new interfaces also. Which brings us back to IRibbonExtensibility. We could cover all the other new interfaces with containment, but we can’t cover ribbon customization with containment. And, how do we achieve aggregation without interfering with the add-in code?

For the skinny on this, see next week’s exciting adventure of The COM Shim Wizard!!!

Low-level support for ICustomTaskPaneConsumer, IRibbonExtensibility, FormRegionStartup, etc.

andreww — Sun, 24 Dec 2006 00:50:00 GMT

I’m mostly interested in the runtime aspects of VSTO, and less interested in the RAD design-time aspects (however wonderful they are), and in this post I want to explore some of the low-level infrastructure that the VSTO runtime provides. As a developer building add-ins using VSTO, you mostly (and rightly) don’t care how the plumbing works, so long as it works, and you won’t ever code against the low-level infrastructure directly. However, there’s a middle level which you could code against if you wanted to – after all, some people do prefer to stay close to the bare metal, and don’t need the hand-holding that visual designers provide.

Back in the mists of time (well, April anyway), I explained how the VSTO support for new Office extensibility interfaces was evolving, and how we focus on the more critical runtime elements before we layer on design-time support. You can read my earlier post here.

At that time, I was talking about early CTP releases of VSTO ‘v3’ (Orcas), although we used the same model in VSTO 2005 SE (Cypress), which shipped at the beginning of Nov-06. Because SE was such an extremely short-cycle release, you can think of it as a snapshot of our design thinking for Orcas – our evolving Orcas support was frozen in time in the SE release. Specifically, SE includes full runtime support for the new extensibility interfaces introduced in Office 2007, and a minimal level of design-time support for these. Of course, we’re aiming to provide more extensive design-time support in Orcas.

In SE, we do have simple wrappers for ICustomTaskPaneConsumer, specifically so that developers can retain the “one line of code” experience that they’re used to from using the VSTO doc-level ActionsPane. So, that’s a degree of design-time support, although not in the sense of a visual designer. (Note that while the VSTO programming model for these two task pane types is very similar, the underlying plumbing is completely different, based as they are on two completely different interfaces, with radically different programming models.) The rationale here is that ICustomTaskPaneConsumer is sufficiently interesting an interface to warrant a degree of design-time support, yet a visual designer is unwarranted because you can simply use the Windows Forms UserControl designer for your task pane controls.

Continuing the pattern, SE has a simple design-time experience for IRibbonExtensibility, including a simple “Add item” Ribbon wizard, which behaves in a “fire and forget” fashion. Finally, SE has zero design-time support for FormRegionStartup.

So, to create a custom task pane using the SE design-time support, you design a custom UserControl, then call the Add method on the VSTO CustomTaskPanes collection object exposed in the add-in class, like so:

UserControl1 uc = new UserControl1();

CustomTaskPane taskPane = CustomTaskPanes.Add(uc, "Contoso");

taskPane.Visible = true;

To create a custom Ribbon, you invoke the SE design-time Ribbon item wizard, which generates a Ribbon XML file and a class that implements IRibbonExtensibility.

[ComVisible(true)]

public class RibbonX : Office.IRibbonExtensibility

{

The Ribbon item wizard also gives you another part of the ThisAddIn partial class, specifically with an override of the RequestService virtual method:

public partial class ThisAddIn

{

private RibbonX ribbon;

protected override object RequestService(Guid serviceGuid)

{

if (serviceGuid == typeof(Office.IRibbonExtensibility).GUID)

{

if (ribbon == null)

{

ribbon = new RibbonX();

}

return ribbon;

}

return base.RequestService(serviceGuid);

}

It’s this RequestService method that is your code’s exposure to the underlying VSTO runtime plumbing that will allow your add-in to implement any of the new extensibility interfaces. Right now, VSTO supports three: ICustomTaskPaneConsumer, IRibbonExtensibility and FormRegionStartup, but the point is that later versions of Office could implement any number of additional extensibility interfaces. So long as the Office apps keep querying the add-in for the new interfaces in the same way, the plumbing underlying RequestService should continue to function correctly with these new interfaces, without change. All you have to do in your add-in is to override RequestService to return the appropriate object that implements the interface(s) you want to support. Obviously, as new interfaces are introduced, we will test them thoroughly against this runtime mechanism so that we can support them “officially” as well as “technically”.

Getting back to Ribbon for a moment, because SE has no VSTO wrapper for IRibbonExtensibility, and only a non-re-entrant Ribbon item wizard, any customization you want to make in an SE add-in to the Ribbon controls and their behavior means manually editing the XML and manually adding callbacks to the custom Ribbon class.

At the extreme with zero design-time support, if you want to implement a custom form region in an add-in, you have to create a class manually that implements FormRegionStartup:

[ComVisible(true)]

public class FormRegionX : Outlook.FormRegionStartup

{

…and you’re completely on your own in SE, with no design-time support of any kind.

The main point I want to make in this post is to focus on the low-level plumbing that supports an open-ended number of new extensibility interfaces. So, let’s take all design-time support out of the picture to level the playing field. Suppose you want to build a VSTO add-in that takes advantage of the runtime RequestService support, but you want to implement all the extensibility interfaces yourself without any wizard interference?

For Ribbon, it’s easy, since all the Ribbon item wizard does is to generate for you a class that implements the interface (and some simple XML to get you started with the Ribbon markup), and clearly you could do this entirely manually if you had to. Here’s a simple class that implements IRibbonExtensibility, pretty much as the Ribbon item wizard would generate, and a good starting point if you want to implement the interface manually:

[ComVisible(true)]

public class RibbonX : Office.IRibbonExtensibility

{

private Office.IRibbonUI _ribbon;

public RibbonX()

{

}

public void OnLoad(Office.IRibbonUI ribbonUI)

{

_ribbon = ribbonUI;

}

public string GetCustomUI(string ribbonID)

{

return Properties.Resources.RibbonX;

}

public void OnToggleButton(

Office.IRibbonControl control, bool isPressed)

{

Globals.ThisAddIn._taskPaneX._taskPane.Visible = isPressed;

}

Note, that this code assumes that I’ve put the RibbonX.xml into my project resources (so that I get a typed member of the Resources class called RibbonX). I’ve also implemented the OnToggleButton callback to toggle the visibility of a custom task pane – this is a custom field I’m going to add to my ThisAddIn class.

Here’s a similar class that implements ICustomTaskPaneConsumer manually – all we have to do is to cache the task pane factory that Office gives us, and use it at any point thereafter to create custom task panes. To create a custom task pane, we invoke the factory’s CreateCTP method, specifying the ProgId of the control that we want Office to create for us:

public class TaskPaneX : Office.ICustomTaskPaneConsumer

{

private Office.ICTPFactory _taskPaneFactory;

internal Office.CustomTaskPane _taskPane;

public void CTPFactoryAvailable(Office.ICTPFactory CTPFactoryInst)

{

try

{

_taskPaneFactory = CTPFactoryInst;

_taskPane = _taskPaneFactory.CreateCTP(

"ContosoAddin.SimpleControl", "SimpleControl", Type.Missing);

}

catch (Exception ex)

{

MessageBox.Show(ex.ToString());

}

In the above example, the string “ContosoAddin.SimpleControl” is the ProgId of a custom UserControl in my project – it could just as easily be any ActiveX control or any managed control exposed (and registered) as an ActiveX control. Note that my task pane class doesn’t need to be ComVisible, although of course my UserControl class does. It’s not necessary to make the whole add-in assembly ComVisible, just selected classes. On the other hand, you do need to set the build property to register the add-in for COM interop – this will also register my SimpleControl as an ActiveX control. Here’s the non-designer part of my SimpleControl class:

[ComVisible(true)]

[ProgId("ContosoAddin.SimpleControl")]

[Guid("918E7B30-E23A-4226-85A2-181ABB514C66")]

public partial class SimpleControl : UserControl

{

public SimpleControl()

{

InitializeComponent();

}

Finally, here’s the code in my ThisAddIn class to hook everything up: I have a field for both of my classes that implement extensibility interfaces, and I return this field when Office queries for the corresponding interface.

private RibbonX _ribbonX;

internal TaskPaneX _taskPaneX;

protected override object RequestService(Guid serviceGuid)

{

if (serviceGuid == typeof(Office.ICustomTaskPaneConsumer).GUID)

{

if (_taskPaneX == null)

{

_taskPaneX = new TaskPaneX();

}

return _taskPaneX;

}

else if (serviceGuid == typeof(Office.IRibbonExtensibility).GUID)

{

if (_ribbonX == null)

{

_ribbonX = new RibbonX();

}

return _ribbonX;

}

return base.RequestService(serviceGuid);

}

As you can see, all I’m doing is overriding RequestService to test specifically for the two interfaces I want to implement, ICustomTaskPaneConsumer and IRibbonExtensibility. The same would apply for other new extensibility interfaces. Simple, no? Of course, there’s no need to code down at this level if you have higher-level design-time support – including the simple design-time support we shipped with VSTO 2005 SE. In the next release of VSTO, we’ll have even more comprehensive visual designer support. The point is merely to shine a little light on the underlying plumbing.

Synchronizing Ribbon and Task Pane

andreww — Sat, 21 Oct 2006 04:18:00 GMT

The new custom task pane model in Office 2007 is interesting. It certainly opens up a wide range of opportunities for providing a better user experience than the doc-level ISmartDocument-based task pane. It’s also interesting in that it provides some challenges for Word and InfoPath developers – see previous post.

The thing that’s most immediately obvious is that individual add-in developers now have a lot of freedom in how they design the resulting user experience. Office provides the basic framework for hooking up your task pane, and it leaves you to implement the task pane in whatever way you see fit. Consider that, unlike the task pane in Office 2003, the new task pane does not stack. Rather, it tiles. So, if the application is running say 10 add-ins, and each add-in implements one or more task panes, if they’re all visible at the same time, the user will run out of screen real estate pretty fast.

To mitigate this, the Office UI guidelines suggest that you should never develop an add-in which programmatically forces the task pane on the user outside their control. Your custom task pane should not be visible on startup, and the user should always be able to make it visible or hidden at will. The simplest approach is to provide a ribbon button to allow the user to toggle the task pane visibility.

By implication, you should never assume in your add-in code that your task pane is visible at any given time. That means you need to sink the VisibleChangedEvent on your task pane so you always know its state – the user might open/close your task pane via the custom ribbon button you conveniently supply, but they might also simply hit the X box to close it directly. By further implication, you’re responsible for synchronizing the toggled state of your ribbon button (assuming you’re providing a togglebutton) to the actual state of the task pane.

Here’s how you could set this up in a very simple way. The following code snippets assume you’ve created a VSTO add-in and added a simple ribbon class (via the Add Item project wizard). Here’s the markup for my togglebutton:

<toggleButton id="standardToggle"

label="Standard"

onAction="OnStandardToggle"

getPressed="GetPressed"/>

The interesting stuff in my ribbon class is after the #region block for “standard stuff”:

[ComVisible(true)]

public class RibbonX : Office.IRibbonExtensibility

{

#region Standard stuff

private Office.IRibbonUI ribbon;

public RibbonX()

{

}

public void OnLoad(Office.IRibbonUI ribbonUI)

{

this.ribbon = ribbonUI;

}

public string GetCustomUI(string ribbonID)

{

return Properties.Resources.RibbonX;

}

#endregion

private bool isTaskPaneVisible;

public bool IsTaskPaneVisible

{

get { return isTaskPaneVisible; }

set

{

isTaskPaneVisible = value;

ribbon.InvalidateControl("standardToggle");

}

public bool GetPressed(Office.IRibbonControl control)

{

switch (control.Id)

{

case "standardToggle":

return isTaskPaneVisible;

default:

return false;

}

public void OnStandardToggle(Office.IRibbonControl control, bool isPressed)

{

Globals.ThisAddIn.ctp.Visible = isPressed;

}

So, I have a bool field in my ribbon class, exposed via a property which invalidates my ribbon togglebutton inside the setter. Invalidating my control will make Office call back to my GetPressed method. In my GetPressed method, I return the current value of the flag I’m using to cache the visible state of my task pane. When the user clicks my togglebutton, I set the visible state of the task pane.

Over in my add-in’s main class, I make sure my CustomTaskPane field is accessible to my ribbon class. I create the task pane in my Startup method, and at the same time I hook up an event handler for the VisibleChanged event. When I get this event, I toggle the state of the bool flag in my ribbon class:

private RibbonX ribbon;

internal CustomTaskPane ctp;

private void ThisAddIn_Startup(object sender, System.EventArgs e)

{

this.Application = (Excel.Application)ExcelLocale1033Proxy.Wrap(typeof(Excel.Application), this.Application);

ctp = this.CustomTaskPanes.Add(new ContosoAqua.ContosoControl(), "Contoso");

ctp.Visible = false;

ctp.VisibleChanged += new EventHandler(ctp_VisibleChanged);

}

void ctp_VisibleChanged(object sender, EventArgs e)

{

ribbon.IsTaskPaneVisible = !ribbon.IsTaskPaneVisible;

}

Pretty simple, yes?

Another thing you should do is to design your add-in so that it does not need multiple task panes. One way to achieve this is to use a TabControl on your task pane – this is a very simple and cheap mechanism to provide your users with multiple different controls for each different context that you’ve identified for your solution, yet at the same time reduce the impact on their screen real estate.

Implementing such a task pane is pretty trivial. Here’s one I built earlier – I have a UserControl with a TabControl with 3 tabs. I’ve populated each tab with the controls I want for that context (actually, I created a separate UserControl with the controls I wanted for each tab). Then create a CustomTaskPane using the outer UserControl, and Robert is your father’s brother: