Windows Template Library - WTL Version 7.0 (build 2088) 03/29/02

Copyright (C) 1997-2002 Microsoft Corporation All rights reserved.
This file is a part of Windows Template Library. The code and information is provided "as-is" without warranty of any kind, either expressed or implied.

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

File Name: | Description:

readme.htm | this file
include\
atlapp.h | message loop, interfaces, general app stuff
atlcrack.h | message cracker macros
atlctrls.h | standard and common control classes
atlctrlw.h | command bar class
atlctrlx.h | bitmap button, check list view, and other controls
atlddx.h | data exchange for dialogs and windows
atldlgs.h | common dialog classes, property sheet and page classes
atlframe.h | frame window classes, MDI, update UI classes
atlgdi.h | DC classes, GDI object classes
atlmisc.h | WTL ports of CPoint, CRect, CSize, CString, etc.
atlprint.h | printing and print preview
atlres.h | standard resource IDs
atlscrl.h | scrollable windows
atlsplit.h | splitter windows
atltheme.h | Windows XP theme classes
atluser.h | menu class
samples\
Alpha\... | Windows XP 32-bit (alpha) toolbar images
BmpView\... | bitmap file view sample
MTPad\... | multithreaded notepad sample
MDIDocVw\... | WTL version of the MDI sample
GuidGen\... | WTL version of the GuidGen sample
appwiz60\
setup.js | AppWizard setup program
atlapp60.awx | WTL AppWizard for VC++ 6.0
appwiz70\
setup.js | AppWizard setup program
Files\... | WTL AppWizard for VC++ 7.0 files

4. Class Overview

usage: | mi base | - | a base class (multiple inheritance)
| client | - | wrapper class for a handle
| as-is | - | to be used directly
| impl | - | implements a window (has WindowProc) or other support
| helper | - | a helper class
| base | - | implementation base class

class name: | usage: | description:
app/module support
CAppModule |  | app support, CComModule derived
CServerAppModule |  | module for COM servers
CMessageLoop | as-is | message loop
CMessageFilter | mi base | message filter interface
CIdleHandler | mi base | idle time handler interface
frame windows
CFrameWindowImplBase<> | base |
CFrameWindowImpl<> | impl | frame window support
COwnerDraw<> | impl mi base | owner-draw msg map and handlers
CDialogResize<> | impl mi base | support for resizing dialogs
MDI windows
CMDIWindow | client | MDI methods
CMDIFrameWindowImpl<> | impl | MDI frame window
CMDIChildWindowImpl<> | impl | MDI child window
update UI
CUpdateUIBase | base |
CUpdateUI<> | mi base class | provides support for UI update
standard controls
CStatic | client | static ctrl
CButton | client | button ctrl
CListBox | client | list box ctrl
CComboBox | client | combo box ctrl
CEdit | client | edit ctrl
CEditCommands | mi | standard edit command support
CScrollBar | client | scroll bar ctrl
common controls
CImageList | client/impl | image list
CListViewCtrl | client | list view ctrl
CTreeViewCtrl | client | tree view ctrl
CTreeItem | helper |
CTreeViewCtrlEx | client | uses CTreeItem
CHeaderCtrl | client | header bar ctrl
CToolBarCtrl | client | toolbar ctrl
CStatusBarCtrl | client | status bar ctrl
CTabCtrl | client | tab ctrl
CToolTipCtrl | client | tool tip ctrl
CToolInfo | helper |
CTrackBarCtrl | client | trackbar ctrl
CUpDownCtrl | client | up-down ctrl
CProgressBarCtrl | client | progress bar ctrl
CHotKeyCtrl | client | hot key ctrl
CAnimateCtrl | client | animation ctrl
CRichEditCtrl | client | rich edit ctrl
CRichEditCommands | mi | std rich edit commands support
CDragListBox | client | drag list box
CDragListNotifyImpl<> | impl mi class | support for notifications
CReBarCtrl | client | rebar ctrl
CComboBoxEx | client | extended combo box
CDateTimePickerCtrl | client | date-time ctrl
CFlatScrollBarImpl | mi impl | flat scroll bars support
CFlatScrollBar | as-is | flat scroll bars support
CIPAddressCtrl | client | IP address ctrl
CMonthCalendarCtrl | client | month calendar ctrl
CCustomDraw<> | impl mi class | custom draw handling support
property sheet & page
CPropertySheetWindow | client |
CPropertySheetImpl<> | impl | property sheet
CPropertySheet | as-is |
CPropertyPageWindow | client |
CPropertyPageImpl<> | impl | property page
CPropertyPage | as-is |
CAxPropertyPageImpl<> | impl | property page with ActiveX
CAxPropertyPage | as-is |
common dialogs
CFileDialogImpl<> | impl | GetOpenFileName/GetSaveFileName
CFileDialog as-is |  |
CFolderDialogImpl | impl | directory picker
CFolderDialog | as-is |
CFontDialogImpl<> | impl | ChooseFont common dialog
CFontDialog | as-is |
CRichEditFontDialogImpl<> | impl | ChooseFont for rich edit
CRichEditFontDialog | as-is |
CColorDialogImpl<> | impl | ChooseColor common dialog
CColorDialog | as-is |
CPrintDialogImpl<> | impl | PrintDlg common dialog
CPrintDialog | as-is |
CPrintDialogExImpl | impl | new Win2000 print dialog
CPrintDialogEx | as-is |
CPageSetupDialogImpl<> | impl | PageSetupDlg common dialog
CPageSetupDialog | as-is |
CFindReplaceDialogImpl<> | impl | FindText/ReplaceText
CFindReplaceDialog | as-is |
USER support
CMenu | client | menu support
GDI support
CDC | client | DC support
CPaintDC | client | for handling WM_PAINT
CClientDC | client | for GetDC
CWindowDC | client | for GetWindowDC
CPen | client | GDI pen object
CBrush | client | GDI brush object
CFont | client | GDI font object
CBitmap | client | GDI bitmap object
CPalette | client | GDI palette object
CRgn | client | GDI rgn object
enhanced controls
CCommandBarCtrlImpl | impl | command bar
CCommandBarCtrl | as-is |
CBitmapButtonImpl | impl | bitmap button
CBitmapButton | as-is |
CCheckListViewCtrlImpl | impl | check list box
CCheckListViewCtrl | as-is |
CHyperLinkImpl | impl | hyper link control
CHyperLink | as-is |
CWaitCursor | as-is | wait cursor
CMultiPaneStatusBarCtrlImpl | impl | status bar with multiple panes
CMultiPaneStatusBarCtrl | as-is |
CPaneContainerImpl<> | impl | pane window container
CPaneContainer | as-is |
additional UI components
CScrollImpl | impl | scrolling support
CScrollWindowImpl | impl | scrollable window
CMapScrollImpl | impl | scrolling support with map modes
CMapScrollWindowImpl | impl | scrollable window with map modes
CSplitterImpl | impl | splitter support
CSplitterWindowImpl | impl | splitter window
CSplitterWindow | as-is |
theming support
CTheme | client | Windows XP theme
CThemeImpl<> | impl | theming support for a window
printing support
CPrinterInfo<> | as-is | print info support
CPrinter | client | printer handle wrapper
CDevMode | client | DEVMODE wrapper
CPrinterDC | client | printing DC support
CPrintJobInfo | client | print job info
CPrintJob | client | print job support
CPrintPreview | mi | print preview support
CPrintPreviewWindow | as-is | print preview window
miscellaneous
CSize | as-is | WTL port of MFC's CSize
CPoint | as-is | WTL port of MFC's CPoint
CRect | as-is | WTL port of MFC's CRect
CString | as-is | WTL port of MFC's CString
CWinDataExchange | mi | data exchange for controls
CRecentDocumentList | mi or as-is | support for MRU list

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 -