WTL doc

WTL Makes UI Programming a Joy

Part 2: The Bells and Whistles

Recall from Part 1 of this series, that the Windows Template Library (WTL) is available on the January 2000

Platform SDK and beyond. It’s an SDK sample produced by members of the ATL team chartered with

building an ATL-based wrapper around the windowing portions of the Win32 API. In Part I, I covered WTL’s

support for SDI, Multi-SDI, MDI, and explorer/workspace-style applications that use command bars, splitters,

GDI wrappers, helper classes, and DDX. In Part II, I’ll give you a look into WTL’s common controls

wrappers, common dialog wrappers, property sheets, printing, print preview, scrolling support, message

Before I start adding features, I need to remove some. Because BmpView should be able to open BMP files,

but doesn't save them (WTL is not PhotoDraw, after all), I need to remove menu items for saving files. I also

need menu items for printing, page setup, and print preview. All these changes require me to modify

resources of the application, adding or removing menu items and toolbar buttons. The modified application

is shown in Figure 1.

Figure 1: The Modified Application

Instead of the built-in Win32 menu bars, the wizard-generated code uses a WTL command bar for that

polished, modern look. Command bars look like a specialized toolbar, but with menu items instead of the

toolbar buttons. Command bars also provide images for drop-down menu items, which assist in recognizing

commands by providing a visual link between a text label and a corresponding toolbar button. Part I showed

window and display the menu using TrackPopupMenu windows API. Unfortunately, like the built-in menu

bars, Win32 context menus don’t show images. Luckily, the same class that I use to show the menu

command bar can also be used to show images on a context menu. The command-bar class in WTL,

CCommandBarCtrl

1

, has a method called TrackPopupMenu that you can use to display a context menu,

which is nearly identical to the TrackPopupMenuEx Win32 API function:

BOOL

CCommandBarCtrlImpl::TrackPopupMenu(

HMENU hMenu,

UINT uFlags,

portion of it to display our context menu. While all of that can be done using Win32 API and menu handles, it

is more convenient to have a class that wraps a menu. Luckily, WTL provides such a class. Just like the GDI

classes discussed in Part I, there are two classes that wrap an HMENU: CMenu and CMenuHandle. CMenu is

the managed version and destroys the HMENU when it goes out of scope. CMenuHandle is unmanaged and

does nothing in its destructor.

Let's now see how I use all of this for our context menu. In the main window class, CMainFrame, I'll handle

the WM_CONTEXTMENU message. If the message comes from the view window, I'll load and display the

context menu. Here is the code:

LRESULT CMainFrame::OnContextMenu(

UINT, WPARAM wParam, LPARAM lParam, BOOL& bHandled) {

GET_X_LPARAM(lParam), GET_Y_LPARAM(lParam));

}

else bHandled = FALSE;

return 0;

}

You can see that I used CMenu class to load the menu resource. That menu will be automatically destroyed

when the CMenu object goes out of scope. To get the popup menu, I used the unmanaged version,

CMenuHandle. Because the popup menu is a part of the parent menu, there is no need to destroy it

separately. When I have the menu loaded, I use the command bar object, m_CmdBar to call its

TrackPopupMenu method to display the context menu. Because the command bar has all the menu item

The WTL App Wizard created a view class for us. I will use that class to display bitmaps. The App Wizard

implement the OnPaint handler to display the bitmap. However, bitmaps can be of any size, and that size

can be bigger than the window I have. I need to allow users to scroll and see the whole bitmap.

Scrolling allows you to view different portions of the window than display by default. Some of the standard

Windows controls already provide support for this, so you don't have to do any additional work. But, if you

draw the content of the window yourself like I am, you need to write code to support scrolling. WTL provides

classes to help you implement a window that has built in support for scrolling and makes it much easier to

draw without a regard to what is the current visible area. The classes let you concentrate only on the

presentation area that you want to draw, and ignore the current scroll state of the window.

WTL provides two classes for the basic scrolling support: CScrollImpl, and CScrollWindowImpl.

CScrollImpl is a template class that provides generic scrolling support that you can add to any window

basic ones; CMapScrollImpl derives from CScrollImpl and adds support for the mapping modes;

CMapScrollWindowImpl adds a message map for the full-window implementation. Support for mapping

modes allows you to easily use the coordinate system and units that are the best fit for your content.

Regardless of your scrolling implementation base class, you still need to do two things: set the size of your

content (so the scrolling can happen properly), and do the actual drawing (no amount of template based

classes will ever save you from that). However, you do not have to handle the WM_PAINT message or worry

about which part of the content of your window to draw, relative to the current scroll position. Instead, you

set the SetScrollSize and implement the DoPaint method. Setting the size of the scroll region is done

with any number of overloaded CScrollImpl helper functions called SetScrollSize:

void SetScrollSize(int xMin, int yMin, int xMax, int yMax,

Yep. That last parameter defaults to NULL instead of TRUE. Unfortunately, this will cause bRedraw to

default to FALSE instead of TRUE when using a SIZE structure.

this when the bitmap to display changes:

class CBitmapView : public CScrollWindowImpl<CBitmapView> {

…

void SetBitmap(HBITMAP hBitmap) {

if(!m_bmp.IsNull()) m_bmp.DeleteObject();

m_bmp = hBitmap;

if(!m_bmp.IsNull()) m_bmp.GetSize(m_size);

else m_size.cx = m_size.cy = 1;

SetScrollOffset(0, 0, FALSE);

allow you to draw your content with the upper left hand corner adjusted for the current scroll position. It’s not

really so complicated as it seems, as shown in the CScrollImpl class’s implementation of OnPaint:

LRESULT CScrollImpl::OnPaint(UINT, WPARAM wParam, LPARAM, BOOL&) {

T* pT = static_cast<T*>(this);

ATLASSERT(::IsWindow(pT->m_hWnd));

if(wParam != NULL) { // The HDC is sometimes passed in

}

else {

Our view’s implementation of DoPaint does pretty much what you’d expect:

class CBitmapView : public CScrollWindowImpl<CBitmapView> {

…

void DoPaint(CDCHandle dc) {

if(!m_bmp.IsNull()) {

CDC dcMem;

dcMem.CreateCompatibleDC(dc);

HBITMAP hBmpOld = dcMem.SelectBitmap(m_bmp);

dc.BitBlt(0, 0, m_size.cx, m_size.cy, dcMem, 0, 0, SRCCOPY);

dcMem.SelectBitmap(hBmpOld);