Welcome to the Windows Template Library, version 7.0. This document contains the following topics:

1. Introduction
2. Features And Installation
3. Packing List
4. Class Overview
5. ATL/WTL AppWizard
6. Changes Between WTL 3.1 And 7.0
7. Changes Between WTL 3.0 And 3.1

1. Introduction

Windows Template Library, or WTL, is a set of classes that extend ATL to support more complex user interfaces for either applications or various UI components, while maintaining the big advantage of ATL - small and fast code. WTL classes were designed to be the best and the easiest way to implement rich Win32 based UI for ATL based applications, servers, components, and controls.

WTL provides support for implementing various user interface elements, from frame and popup windows, to MDI, standard and common controls, common dialogs, property sheets and pages, GDI objects, UI updating, scrollable windows, splitter windows, command bars, etc. The WTL classes are mostly templated and use minimal instance data and inline functions. They were not designed as a framework, so they do not impose a particular application model, and can accommodate any. The classes do not use hooks or thread local storage, so they have no restrictions that those techniques impose. They also have no inter-dependencies and can be freely mixed with straight SDK code. In summary, WTL delivers very small and efficient code, very close in size and speed to SDK programs, while presenting a more logical, object oriented model to a programmer.

2. Features And Installation

This is the third public release of WTL, after WTL 3.0 and 3.1. It brings full support for the new Common Controls and themes in Windows XP, and well as support for Visual Studio .NET and ATL 7.0. It also provides fixes and enhancements to the previously available classes that implement command bars, scrollable windows, splitter windows, printing, bitmap buttons, etc. The classes can be used with either VC++ 6.0 and ATL 3.0 or VC++ .NET and ATL 7.0, and App Wizards for both environments are included.

The WTL classes are provided in header files located in the include directory. The only header files that must be included is atlapp.h, while others can be used when needed. The name of the file doesn't mean that you have to create an application, just that atlapp.h contains base definitions required for WTL projects.

To install WTL, just copy the whole directory structure, or unpack the archive file, to the location of your choice. Please be sure to add the WTL\include directory to the list of include directories in VC++, so that the compiler can find them when you include them in your projects..

Setup programs for both App Wizards are provided in their directories. After executing the setup scripts, App Wizards will appear in the list of App Wizards when you select File.New.Project in VC++ IDE.

To manually install AppWizard for VC++ 6.0, just copy the file AppWiz60\AtlApp60.awx to the custom app wizard directory in the VC++ installation, %VC6DIR%\Common\MSDev98\Template, where %VC6DIR% is the directory where VC++ 6.0 is installed.

To manually install App Wizard for VC++ 7.0, copy all WTLApp70.* files from AppWiz70\Files to VC++ .NET projects directory, %VC7DIR%\Vc7\vcprojects, where %VC7DIR% is the directory where VC++ .NET is installed. After that,  open WTLApp70.vsz and modify the like that contains ABSOLUTE_PATH to contain %WTLDIR%\AppWiz70\Files, where %WTLDIR% is the directory where WTL files are.

3. Packing List

4. Class Overview

5. ATL/WTL AppWizard

ATL/WTL AppWizard generates starting code for a WTL app. It has options to create code for different app types and features.

You can choose the following options:

• Application type (SDI, multi thread SDI, MDI, dialog based)
• Support for hosting ActiveX controls
• COM server support
• Class implementation in .CPP files
• Common Control manifest
• Toolbar, rebar, command bar, status bar
• View window, and it's type (generic, dialog based form, or a list box, edit, list view, tree view, rich edit based, HTML page)
• For dialog based apps or a form based view window - support for hosting ActiveX controls in the dialog

There are 2 versions of the App Wizard provided with WTL - one for VC++ 6.0, and the other for VC++ .NET (7.0). They can be used only in corresponding versions of the VC++ IDE.

6. Changes Between WTL 3.1 And 7.0

New classes and features:

Support for new Common Controls v6 messages

Support for Visual Studio .NET and ATL 7.0

WTLApp70 - new App Wizard for Visual Studio .NET

CThemeImpl - implements support for Windows XP themes

CMDICommandBarCtrl - implements Command Bar for MDI applications

Fixes and enhancements:

Command Bar:

• Bogus assert in OnDestroy
• Check marks can be truncated in large font settings
• Use pT to access GetSystemSettings, DrawMenuText, DrawBitmapDisabled, Draw3DCheckmark, DoPopupMenu, DoTrackPopupMenu, TakeFocus, GiveFocusBack, so they can be overridden
• No hot-tracking if main window is not active
• Top level items not painted inactive if app looses activation while drop down menu is displayed
• Added Windows XP flat menus support
• Drop-down menu doesn't close if clicked again (Windows XP only)
• Menu item text and accelerator text too close with some settings
• Keyboard can still access clipped menu items
• Added support for hiding keyboard navigation indicators until Alt key is pressed (system setting)
• Added AddIcon and ReplaceIcon variants for icon resources
• Image size calculated differently in different places
• Add support for 32-bit (alpha channel) bitmaps for Windows XP
• Fixed width calculation for default menu items

 

CFrameWindowImpl:

• AddSimpleReBarBandCtrl sets toolbar extended styles without preserving old ones
• PrepareChevronMenu should not create menu items for buttons with TBSTATE_HIDDEN
• TPM_VERPOSANIMATION will not be defined in atlframe.h if atlctrlw.h is included first
• CreateSimpleToolBarCtrl - height might be too small if large font is used
• PrepareChevronMenu uses TB_GETBUTTONTEXT, better use TB_GETBUTTONINFO
• Chevron menu doesn't close if clicked again (Windows XP only)
• Should check local classes for superclassing
• Add support for 32-bit (alpha channel) bitmaps for Windows XP

 

Update UI:

• UISetText can clear other menu item flags
• CUpdateUI::UIUpdateState assigns value with |= instead of =
• Added UISetDefault() and fix default state to work with menus

 

CString:

• GetBuffer() and GetBufferSetLength() should return NULL in out-of-memory condition
• Added missing methods: separate c-tors for LPCSTR and LPCWSTR, CollateNoCase, TrimRight and TrimLeft variants, Find variants, moved FormatV to public
• Fix _IsValidString usage
• FormatV incorrectly calculates buffer size (too big)
• Usage of _ttoi causes problems with _ATL_MIN_CRT in VC7

 

CDC:

• GetTabbedTextExtent() should return DWORD instead of BOOL
• Add FillRect() that accept color index instead of a brush handle
• DrawDragRect() leaks regions and a brush
• Improved DitherBlt() - added brushes as arguments for used colors
• Added DrawShadowText() (uses LoadLibrary/GetProcAddress to run on older Windows)

 

CListViewCtrl:

• SetItemState should use LVM_SETITEMSTATE
• SetItemCount should return a BOOL

 

CRichEditCtrl:

• Added SetCharFormat() variant that accepts flags (for SCF_ALL)
• CharFromPos() should pass a pointer to POINTL in lParam
• GetTextRange() - should add Unicode variant for rich edit version >= 2
• Added another FormatRange() that can accept a pointer to FORMATRANGE (needed for passing NULL to clear cache)

 

CHyperLink:

• Allow overriding of Navigate and CalcLabelRect
• Doesn't handle right or center alignment

 

CColorDialog:

• Has static variables that were not initialized with _ATL_MIN_CRT
• Fixed HookProc for ColorOK message - the message is not sent, but the hook proc is called directly

 

atlcrack.h:

• MSG_WM_TIMER crack macro should cast to TIMERPROC instead of TIMERPROC*
• Add cracked handlers for all new messages in Common Controls 6

 

atlapp.h:

• Fixed problems with atlTraceUI with ATL7
• #ifdefs for ATL7 were in the wrong place

 

atlctrls.h:

• Add support in control classes for all new messages in Common Controls 6

 

CRecentDocumentList:

• AtlCompactPath corrupts memory if filename is longer than requested compact size
• ReadFromRegistry incorrectly checks for error when reading from registry

 

CSplitterWindow:

• Incorrect calculation of middle position
• 3D border now drawn only if WS_EX_CLIENTEDGE is set

 

Printing:

• Uses DWORD instead of an int for a job ID
• CPrintJob::CancelPrintJob shouldn't have a return value

 

Misc:

• CRegKey::QueryValue and SetValue are deprecated in ATL7
• Added direct support for ATL7
• Replace ScreenToClient and ClientToScreen with MapWindowPoints to support RTL layout
• CFindFile::GetFilePath(LPTSTR...) returns path without the file name
• MDI: Updating client edge in WM_WINDOWPOSCHANGING causes minimize/maximize/restore animation problems, use WM_WINDOWPOSCHANGED
• Custom Draw: Added CCustomDraw::OnSubItemPrePaint() overrideable method
• CFolderDialogImpl uses 'this' for BROWSEINFO.lParam instead of T*
• CImageList::Destroy shouldn't use Detach()
• ATL7 has its own AtlLoadString
• CPropertySheet doesn't close when you press X button
• Fixed problems for _U_STRINGorID and others that moved from atlbase.h to atlwin.h in ATL7
• Add AtlMessageBox() that accepts either in-memory or resource strings
• CScrollImpl: fixed bug with scrolling child windows
• CPropertyPageImpl: Add new notification handlers to enable direct return values (use #ifdef _WTL_NEW_PAGE_NOTIFY_HANDLERS to use them)
• Add AtlInitCommonControls() to simplify use
• DDX: Fixed usage of the size of char arrays for DDX
• CPageSetupDialog: changed usage of CWndProcThunk because of changes in ATL7
• Fix confusing precedence in expressions
• Removed forward declarations because default values for template arguments shouldn't be specified in two places (we don't need them anyway)
• Win64: Fix /Wp64 warnings from 32-bit VC7 compiler caused by SDK headers
• Fix direct usage of English strings (they can be #defined to something else now)
• AtlGetCommCtrlVersion not defined if _ATL_DLL is in ATL 3.0 (and CmdBar is using it)

 

App Wizard:

• Added manifest for Common Controls 6
• Loading Rich Edit DLL should use HMODULE
• Should not use atlimpl.cpp for ATL7
• Added message handler prototypes to generated files
• VERSION resource always has VALUE "OLESelfRegister" (now only for COM servers)
• Added option for putting implementation in CPP files
• d-tor for the thread manager class in MSDI project executed after the heap is destroyed
• Wrong settings when changing to a dialog project and back (App Wizard 6.0 only)
• Remove cut/copy/paste accelerators for form view and dialogs projects
• Fix toolbar bitmaps so they are not transparent (problem with Windows XP flat menus only)
• Used CMDICommandBarCtrl for MDI apps
• Add symbols required for VC7 Class Wizard to recognize an ATL project
• Changed default styles for the rebar, so it does look OK without CmdBar and with manifest
• Added setup programs for both App Wizards
• Remove ignored resource attributes: MOVEABLE, PURE, etc. (App Wizard 7.0 only)
• Add call to DefWindowProc to WinMain to resolve possible problems if MSLU is used

 

Samples:

• Updated toolbar bitmaps, added #ifdefs for ATL7, added manifest file for CommCtrl6, qualified _U_RECT with WTL namespace, updated use of deprecated CRegKey functions, added VC7 projects
• Added Alpha sample

7. Changes Between WTL 3.0 And 3.1

New classes:

CPaneContainer - implements a window that provides a title bar and a close button (like Explorer)

CDialogResize - an MI class that allows resizing of dialogs (or any windows with child windows/controls)

CAxPropertyPageImpl - implements a property page that can host ActiveX controls

Fixes and enhancements:

CServerAppModule now clears m_hEventShutdown to avoid calling CloseHandle twice

 

CString:

• operator += now leaves original string intact if it's out of memory
• Fixed bad DWORD_PTR usage in TrimRight, TrimLeft, Replace, Remove
• Removed dependencies on CRT for projects that don't use it
• Insert - fixed string corruption in release builds
• Added optional floating point formatting (for projects that use CRT)

 

CEdit and CRichEditCtrl: SetSelAll and SetSelNone had reversed implementation

 

atlres.h: Changed IDs so that they are compatible with MFC's afxres.h

 

Command Bar:

• Added LoadMappedImages()
• Changed handling of left and right arrow keys so that they don't close context menus
• Add code to handle left/right arrow keys correctly on mirrored (RTL) systems
• Removed handler that eats parent window's WM_SETTINGCHANGE
• Fixed bitmap resource leak in Draw3DCheckmark
• Fixed incorrect usage of CharLower in OnMenuChar
• Fixed wrong color for the disabled items in hi-contrast mode
• Added code to gray menu items if main window is inactive
• Fixed keyboard mnemonic handling for IE 4
• Fixed hook problems with multiple cmdbars in the same thread
• Added support for radio menu items
• Added support for disabled top-level menu items (also added in CFrameWindowImpl::PrepareChevronMenu)
• Added keyboard shortcut (Alt+/) to invoke chevron menu
• Added support to override menu item length in a derived class

 

CBitmapButton:

• Bypassed BUTTON DefWindowProc for hover style so that the button doesn't take focus
• Added BMPBTN_AUTOFIRE extended style

 

CDC:

• Added _WTL_FORWARD_DECLARE_CSTRING define to allow usage of methods that accept CString
• Fixed errors in GetTextFace and GetMenuItemString
• Added GetCharWidth32
• Added DrawIconEx method

 

CMenu:

• Implement following missing methods:
      GetMenuDefaultItem
      GetMenuInfo
      GetMenuItemRect
      HiliteMenuItem
      IsMenu
      MenuItemFromPoint
      SetMenuDefaultItem
      SetMenuInfo
• GetMenuString - fixed to include space for terminating NULL character in returning string

 

GDI and USER classes should destroy the GDI/USER objects in Attach if GDI/USER resource is managed

 

CFrameWindowImpl:

• OnToolTipText shouldn't save tool tip text if it's not for a menu
• AddSimpleReBarBandCtrl now adds chevron style only for toolbars with buttons
• AddSimpleReBarBand(Ctrl) - calc band ID if not specified

 

CRecentDocumentList:

• Fix - UpdateMenu deletes wrong menu item when the list is empty
• Added code to allow restricting the number of characters displayed by MRU menu items

 

Update UI:

• Added support for blocking accelerators for disabled items
• Improved search code assuming there are no duplicate entries (and added checks for duplicates)

 

CSplitterWindow:

• CSplitterWindowImpl should derive from CSplitterImpl<T , t_bVertical> to allow overriding of methods
• Added single pane mode and SetSinglePaneMode/GetSinglePaneMode
• Added right/bottom aligned resize mode using extended styles SPLIT_RIGHTALIGNED/SPLIT_BOTTOMALIGNED

 

atlcrack.h: Added handlers for following new messages:
    WM_APPCOMMAND
    WM_NCXBUTTONDOWN
    WM_NCXBUTTONUP
    WM_NCXBUTTONDBLCLK
    WM_XBUTTONDOWN
    WM_XBUTTONUP
    WM_XBUTTONDBLCLK

 

Win64:

• Dialog return value should use DWLP_MSGRESULT and SetWindowLongPtr
• CMenu::InsertMenu, AppendMenu, ModifyMenu should have UINT_PTR for the menu ID
• Added appropriate type casts
• CFrameWindowImpl::m_szAutoName - changed the size to fit the pointer value size
• CListViewCtrl::SortItems should use LPARAM for user data instead of DWORD

 

Misc:

• Added optional mask argument to all methods for setting extended styles
• CMDIWindow::MDIRestore - fixed to send WM_MDIRESTORE instead of WM_MDIICONARRANGE
• CListViewCtrl: Added SortItemsEx method
• CToolBarCtrl::GetButtonInfo - fixed to return int instead of BOOL
• Added CToolBarCtrl::SetButtonSize and SetBitmapSize that accept cx and cy instead of SIZE
• Printing: Changed how GetNewDevModeForPage works (comments in code)
• CFileDialogImpl::_OnTypeChange incorrectly calls pT->OnSelChange instead of pT->OnTypeChange
• CMultiPaneStatusBarCtrl::GetPaneTipText - fixed to use index instead of and ID internally
• CWinDataExchange: Added references to arguments of DoDataExchange, so there are no level 4 warning even if the map is empty
• CPropertySheetWindow: Added new, IE 5.0 specific methods
• CPropertyPageImpl: Added new, IE 5.0 specific methods

 

App Wizard:

• added calls to RemoveMessageFilter and RemoveIdleHandler in CMainFrame::OnDestroy for COM server projects
• added scroll bars for HTML view
• CAppServerModule now handles -embedding as well as -automation
• corrected code in CMainFrame::OnShowToolBar to correctly identify the toolbar in a rebar
• dialog based app code now derives from CUpdateUI as public

- end of readme.htm -