Getting an (ATL) ActiveX control to print from Office Applications

Introduction

Seeing as this is my first ever post to CodeProject, let me do a quick introduction as to who I am and what I do. I have been working in one form of C and C++ or another for as long as I can remember (among the other myriad of languages that I've run into). Nowadays, most of my development is focused on Microsoft Windows platforms, and is done in VC6, VC2002.NET. I am heavily entrenched in BI (Business Intelligence) development, and in my spare time develop little ActiveX controls and games etc...

The plot

Having learnt COM a while ago, I made the obvious progression to ATL to ease the development of boilerplate code, and to leverage off Microsoft's template library. As my experience grew, I ventured into creating ActiveX controls using the ATL framework ... and life was good. I could spew out a fairly useful (albeit not overly complex) control within a short period of time. Recently, I was asked to create a KPI (Key Performance Indicator) control that could be embedded in a web page and an Excel document. Obviously based on my experience (which was obviously not vast) I thought that this would be no problem and off I went, creating code that would meet the functional spec (we all work to these don't we :)).

A couple of days later the control was finished and the final tests were being run when someone asked me to print a hardcopy of an example spreadsheet with the embedded control. This is where my nightmares began. Not only did my control not print, but there was no clear indication as to why it didn't print. And so my exploration into this apparent mystery began.

Have you ever tried to include 3rd party ActiveX controls into an Office document? They sure seem to work fine, but most (apart from the Microsoft controls) don't seem to render themselves when you request a Print Preview or a simple Print of the worksheet or document. So, if any of you have ever had this problem, or have never dabbled with this, but think that you may be heading this way, take note of this, cos it might save you hours of frustration and frantic searching on MSDN and Google.

So what now?

The first thing one needs to realize is that even though we have been blessed with Office 2000 and Office XP, the printing architecture still uses the old Windows-format metafile for its printing operations. This metafile format was used in 16-bit Windows-based applications (thinks back to Win3.1). Now, this becomes a major problem for ActiveX developers who wish their controls to be printable from within Office applications, because this old metafile format only supported a limited set of GDI functionality. The list of supported GDI functions can be found here.

Now that you are armed with your limited function set, you cringe with the realization that you can no longer create memory DC's, you can no longer use your lovely DrawText() functions and you can definitely no longer call GetTextExtentPoint32() function. However, those realizations only hold true for the instance of when your control is being rendered to an old format metafile. So how do we empower our control to know that its being rendered to an old format metafile? Simple, we use the GetObjectType() function and check if the result is equal to OBJ_METADC (old metafile format):

HRESULT Cxxxxx::OnDraw(ATL_DRAWINFO& di)
{
    HDC hdc = di.hdcDraw;
    bool bMetaFile = false;

    //

    // lets check if we're drawing to an old

    // metafile format.. (like Office printing)

    //


    if ( GetObjectType(hdc) == OBJ_METADC )
        bOldMetaFile = true;

    //

    // the rest of your code...

    //

}

For interest, the opposite of OBJ_METADC is OBJ_ENHMETADC (refer to this MSDN document).

Now that we know if we're drawing to an old metafile format or not, we can write adaptive code to cater for each instance or we can just write all our drawing logic using the limited set of functionality that is supported by the old metafile DC.

What about fonts and text extents?

As any ATL ActiveX developer knows, using fonts in AX controls provides for limited amount of fun. The typical piece of code would probably look something like this:

    //

    // ... some code

    //

    CComQIPtr<IFont, &IID_IFont> pFont(m_pFont);
    TEXTMETRICOLE tm;
    if ( pFont != NULL )
    {
        pFont->get_hFont(&newFont);
        pFont->AddRefHfont(newFont);
        pFont->QueryTextMetrics(&tm);
        oldFont = (HFONT) SelectObject(dc, newFont);
    }

The Bolded lines of code are ones that I didn't use regularly, due to the fact that I didn't really need to know about the breakdown of my font's details because I had access to GetTextExtentPoint32() function. Unfortunately, in this scenario, we don't have access to that function to determine how wide (in pixels) our text is going to be. But there is another way to calculate this fairly accurately, as is demonstrated in the code below:

//

// assume that we have called QueryTextMetrics() and

// have a filled TEXTMETRICOLE structure called tm

//

CComBSTR strText(_T("Hello, world"));
SIZE sz;

sz.cx = strText.Length() * tm.tmAveCharWidth;
sz.cy = tm.tmHeight;

Having said this, there are many other functions that I use a lot that I can't use if I want my ActiveX control to be printable by Office, but as with GetTextExtentPoint32() and its respective replacement, there is always a way to replace these functions using Old-Metafile-Safe-Drawing-Code (OMSDC). *maybe that acronym will catch on*

Conclusion

When creating an ActiveX control that you know will be used inside Office applications, and will most probably be printed, remember to stick to these guidelines when developing your drawing logic. I was fairly shocked by how little information was available in the MSDN and online in general, while I was searching for information on how to enable my ActiveX control to print from within an Office application. There are hundreds of documents on ActiveX controls being printed from within Internet Explorer, but none address this particular issue. Perhaps I was looking in the wrong places. Hopefully this article will help one or more of you one day ;)

Acknowledgment

Many thanks to Igor Tandetnik for pointing me in the right direction on this.