(untagged)

WTL Documented

Ben Burnett

0.00/5 (No votes)

1 Jun 2000

Beginning Documentation on WTL

Introduction

Welcome to the Windows Template Library help file, what this file will attept to do is document the Windows Template Library.

WTL Globals

The folowing are defined in the global namespace.

Global functions for stock GDI objects

AtlGetStockBrush

The AtlGetStockBrush function retrieves a handle to one of the stock brushes.

HBRUSH AtlGetStockBrush (

int nBrush

);

Parameters

nBrush[in] - Specifies the type of stock brush. This parameter can be one of the following values.

BLACK_BRUSH

Black brush.

DKGRAY_BRUSH

Dark gray brush.

DC_BRUSH

Windows 98/2000: Solid color brush. The default color is white. The color can be changed by using the SetDCBrushColor function. For more information, see the Remarks section.

GRAY_BRUSH Gray brush.

HOLLOW_BRUSH

Hollow brush (equivalent to NULL_BRUSH).

LTGRAY_BRUSH Light gray brush.

NULL_BRUSH Null brush (equivalent to HOLLOW_BRUSH).

WHITE_BRUSH White brush.

Return Values

If the function succeeds, the return value is a handle to the requested brush.

If the function fails, the return value is NULL.

AtlGetStockFont

The AtlGetStockFont function retrieves a handle to one of the stock fonts.

HFONT AtlGetStockFont (

int nFont

);

Parameters

nFont[in] - Specifies the type of stock font. This parameter can be one of the following values.

ANSI_FIXED_FONT

Windows fixed-pitch (monospace) system font.

ANSI_VAR_FONT

Windows variable-pitch (proportional space) system font.

DEVICE_DEFAULT_FONT

Windows NT/2000: Device-dependent font.

DEFAULT_GUI_FONT Default font for user interface objects such as menus and dialog boxes.

OEM_FIXED_FONT

Original equipment manufacturer (OEM) dependent fixed-pitch (monospace) font.

SYSTEM_FONT System font. By default, the system uses the system font to draw menus, dialog box controls, and text.

SYSTEM_FIXED_FONT Fixed-pitch (monospace) system font. This stock object is provided only for compatibility with 16-bit Windows versions earlier than 3.0.

Return Values

If the function succeeds, the return value is a handle to the requested font.

If the function fails, the return value is NULL.

AtlGetStockPalette

The AtlGetStockPalette function retrieves a handle to one of the stock palettes.

HPALETTE AtlGetStockPalette (

int nPalette

);

Parameters

nPalette[in] - Specifies the type of stock palettes. This parameter can be one of the following values.

DEFAULT_PALETTE

Default palette. This palette consists of the static colors in the system palette.

Return Values

If the function succeeds, the return value is a handle to the requested palette.

If the function fails, the return value is NULL.

AtlGetStockPen

The AtlGetStockPen function retrieves a handle to one of the stock pens.

HPEN AtlGetStockPen (

int nPen

);

Parameters

nPen[in] - Specifies the type of stock pen. This parameter can be one of the following values.

NULL_PEN

Null pen.

BLACK_PEN

Black pen.

DC_PEN

Windows 98/2000: Solid pen color. The default color is white. The color can be changed by using the SetDCPenColor function. For more information, see the Remarks section.

WHITE_PEN

White pen.

Return Values

If the function succeeds, the return value is a handle to the requested pen.

If the function fails, the return value is NULL.

Windows version helpers

AtlIsOldWindows

The AtlIsOldWindows function checks the current OS version.

bool AtlIsOldWindows (

);

Parameters

none

Return Values

Returns true if the current OS is Windows 2000 or greater, false if not.

Global functions for loading resources

AtlLoadAccelerators

The AtlLoadAccelerators function loads the specified accelerator table.

HACCEL AtlLoadAccelerators (

_U_STRINGorID table

);

Parameters

table[in] - String or ID that contains the name of the accelerator table to load.

Return Values

If the function succeeds, the return value is a handle to the loaded accelerator table.

If the function fails, the return value is NULL.

AtlLoadBitmap

The AtlLoadBitmap function loads the specified bitmap resource. This function has been superseded by the AtlLoadBitmapImage function.

HBITMAP AtlLoadBitmap (

_U_STRINGorID bitmap

);

Parameters

bitmap[in] - String or ID that contains the name of the bitmap resource to be loaded.

Return Values

If the function succeeds, the return value is a handle to the bitmap resource.

If the function fails, the return value is NULL.

AtlLoadBitmapImage

The AtlLoadBitmapImage function loads the specified bitmap resource.

HBITMAP AtlLoadBitmapImage (

_U_STRINGorID bitmap,

    UINT fuLoad = LR_DEFAULTCOLOR

);

Parameters

bitmap[in] - String or ID that contains the name of the bitmap resource to be loaded.

fuLoad[in] - This parameter can be one or more of the following values.

Value Meaning

LR_DEFAULTCOLOR The default flag; it does nothing. All it means is "not LR_MONOCHROME".

LR_CREATEDIBSECTION When the uType parameter specifies IMAGE_BITMAP, causes the function to return a DIB section bitmap rather than a compatible bitmap. This flag is useful for loading a bitmap without mapping it to the colors of the display device.

LR_DEFAULTSIZE Uses the width or height specified by the system metric values for cursors or icons, if the cxDesired or cyDesired values are set to zero. If this flag is not specified and cxDesired and cyDesired are set to zero, the function uses the actual resource size. If the resource contains multiple images, the function uses the size of the first image.

LR_LOADFROMFILE Loads the image from the file specified by the lpszName parameter. If this flag is not specified, lpszName is the name of the resource.

LR_LOADMAP3DCOLORS
Searches the color table for the image and replaces the following shades of gray with the corresponding 3-D color:

Color Replaced with

Dk Gray, RGB(128,128,128) COLOR_3DSHADOW

Gray, RGB(192,192,192) COLOR_3DFACE

Lt Gray, RGB(223,223,223)
COLOR_3DLIGHT

Do not use this option if you are loading a bitmap with a color depth greater than 8bpp.

LR_LOADTRANSPARENT
Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (COLOR_WINDOW). All pixels in the image that use that entry become the default window color. This value applies only to images that have corresponding color tables.

Do not use this option if you are loading a bitmap with a color depth greater than 8bpp.

If fuLoad includes both the LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS values, LRLOADTRANSPARENT takes precedence. However, the color table entry is replaced with COLOR_3DFACE rather than COLOR_WINDOW.

LR_MONOCHROME Loads the image in black and white.

LR_SHARED
Shares the image handle if the image is loaded multiple times. If LR_SHARED is not set, a second call to LoadImage for the same resource will load the image again and return a different handle.

When you use this flag, the system will destroy the resource when it is no longer needed.

Do not use LR_SHARED for images that have non-standard sizes, that may change after loading, or that are loaded from a file.

Windows 95/98: The function finds the first image with the requested resource name in the cache, regardless of the size requested.

LR_VGACOLOR Uses true VGA colors.

Return Values

If the function succeeds, the return value is a handle to the bitmap resource.

If the function fails, the return value is NULL.

AtlLoadCursor

The AtlLoadCursor function loads the specified cursor resource. This function has been superseded by the AtlLoadCursorImage function.

HCURSOR AtlLoadCursor (

_U_STRINGorID cursor

);

Parameters

cursor[in] - String or ID that contains the name of the cursor resource to be loaded.

Return Values

If the function succeeds, the return value is a handle to the cursor resource.

If the function fails, the return value is NULL.

AtlLoadCursorImage

The AtlLoadCursorImage function loads the specified cursor resource.

HCURSOR AtlLoadCursorImage (

_U_STRINGorID cursor, 

    UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE,

    int cxDesired = 0,

    int cyDesired = 0

);

Parameters

cursor[in] - String or ID that contains the name of the cursor resource to be loaded.
fuLoad[in] - See AtlLoadBitmapImage

cxDesired[in] - Specifies the width, in pixels, of the cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CXCURSOR system metric value to set the width. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.

cyDesired[in] - Specifies the height, in pixels, of the cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CYCURSOR system metric value to set the height. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.

Return Values

If the function succeeds, the return value is a handle to the cursor resource.

If the function fails, the return value is NULL.

AtlLoadIcon

The AtlLoadIcon function loads the specified icon resource. This function has been superseded by the AtlLoadIconImage function.

HICON AtlLoadIcon (

_U_STRINGorID icon

);

Parameters

icon[in] - String or ID that contains the name of the icon resource to be loaded.

Return Values

If the function succeeds, the return value is a handle to the icon resource.

If the function fails, the return value is NULL.

AtlLoadIconImage

The AtlLoadIconImage function loads the specified icon resource.

HICON AtlLoadIconImage (

_U_STRINGorID icon, 

    UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE, 

    int cxDesired = 0, 

    int cyDesired = 0

);

Parameters

icon[in] - String or ID that contains the name of the icon resource to be loaded.
fuLoad[in] - See AtlLoadBitmapImage

cxDesired[in] - Specifies the width, in pixels, of the icon. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CXICON system metric value to set the width. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.

cyDesired[in] - Specifies the height, in pixels, of the icon. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CYICON system metric value to set the height. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.

Return Values

If the function succeeds, the return value is a handle to the icon resource.

If the function fails, the return value is NULL.

AtlLoadMenu

The AtlLoadMenu function loads the specified menu resource.

HMENU AtlLoadMenu (

_U_STRINGorID menu

);

Parameters

menu[in] - String or ID that contains the name of the menu resource.

Return Values

If the function succeeds, the return value is a handle to the menu resource.

If the function fails, the return value is NULL.

AtlLoadString (BSTR)

The AtlLoadString (BSTR) function loads the specified string resource.

bool AtlLoadString (

UINT uID, 

    BSTR& bstrText

);

Parameters

uID[in] - Specifies the integer identifier of the string to be loaded.

bstrText[out] - Reference to the buffer to receive the string.

Return Values

If the function succeeds, the return value is true, or false if the string resource does not exist. The string is truncated and null terminated if it is longer than the number of characters specified.

AtlLoadString (LPTSTR)

The AtlLoadString (LPTSTR) function loads the specified string resource.

int AtlLoadString (

UINT uID, 

    LPTSTR lpBuffer, 

    int nBufferMax

);

Parameters

uID[in] - Specifies the integer identifier of the string to be loaded.

lpBuffer[out] - Pointer to the buffer to receive the string.

nBufferMax[in] - Specifies the size of the buffer, in TCHARs, or zero if the string resource does not exist. The string is truncated and null terminated if it is longer than the number of characters specified.

Return Values

If the function succeeds, the return value is the number of TCHARs copied into the buffer, not including the null-terminating character, or zero if the string resource does not exist.

AtlLoadSysBitmap

The AtlLoadSysBitmap function loads the specified system bitmap resource. This function has been superseded by the AtlLoadSysBitmapImage function.

HBITMAP AtlLoadSysBitmap (

LPCTSTR lpBitmapName

);

Parameters

lpBitmapName[in] - See AtlLoadSysBitmapImage. The MAKEINTRESOURCE macro can be used to create this value.

Return Values

If the function succeeds, the return value is the handle to the specified system bitmap.

If the function fails, the return value is NULL.

AtlLoadSysBitmapImage

The AtlLoadSysBitmapImage function loads the specified system bitmap resource.

HBITMAP AtlLoadSysBitmapImage (

WORD wBitmapID, 

    UINT fuLoad = LR_DEFAULTCOLOR

);

Parameters

wBitmapID[in] - This parameter can be one or more of the following values.

Bitmap name Bitmap name

OBM_BTNCORNERS OBM_OLD_RESTORE

OBM_BTSIZE OBM_OLD_RGARROW

OBM_CHECK OBM_OLD_UPARROW

OBM_CHECKBOXES OBM_OLD_ZOOM

OBM_CLOSE OBM_REDUCE

OBM_COMBO OBM_REDUCED

OBM_DNARROW OBM_RESTORE

OBM_DNARROWD OBM_RESTORED

OBM_DNARROWI OBM_RGARROW

OBM_LFARROW OBM_RGARROWD

OBM_LFARROWD OBM_RGARROWI

OBM_LFARROWI OBM_SIZE

OBM_MNARROW OBM_UPARROW

OBM_OLD_CLOSE OBM_UPARROWD

OBM_OLD_DNARROW OBM_UPARROWI

OBM_OLD_LFARROW OBM_ZOOM

OBM_OLD_REDUCE OBM_ZOOMD

fuLoad[in] - See AtlLoadBitmapImage

Bitmap name	Bitmap name
OBM_BTNCORNERS	OBM_OLD_RESTORE
OBM_BTSIZE	OBM_OLD_RGARROW
OBM_CHECK	OBM_OLD_UPARROW
OBM_CHECKBOXES	OBM_OLD_ZOOM
OBM_CLOSE	OBM_REDUCE
OBM_COMBO	OBM_REDUCED
OBM_DNARROW	OBM_RESTORE
OBM_DNARROWD	OBM_RESTORED
OBM_DNARROWI	OBM_RGARROW
OBM_LFARROW	OBM_RGARROWD
OBM_LFARROWD	OBM_RGARROWI
OBM_LFARROWI	OBM_SIZE
OBM_MNARROW	OBM_UPARROW
OBM_OLD_CLOSE	OBM_UPARROWD
OBM_OLD_DNARROW	OBM_UPARROWI
OBM_OLD_LFARROW	OBM_ZOOM
OBM_OLD_REDUCE	OBM_ZOOMD

Return Values

If the function succeeds, the return value is the handle to the specified system bitmap.

If the function fails, the return value is NULL.

Remarks

LR_LOADFROMFILE style is added internally to fuLoad by the function.

Bitmap names that begin with OBM_OLD represent bitmaps used by 16-bit versions of Windows earlier than 3.0.

For an application to use any of the OBM_ constants, the constant OEMRESOURCE must be defined before the Windows.h header file is included.

AtlLoadSysCursor

The AtlLoadSysCursor function loads the specified system cursor resource. This function has been superseded by the AtlLoadSysCursorImage function.

HCURSOR AtlLoadSysCursor (

LPCTSTR lpCursorName

);

Parameters

lpCursorName[in] - See AtlLoadSysCursorImage. The MAKEINTRESOURCE macro can be used to create this value.

Return Values

If the function succeeds, the return value is the handle to the specified system bitmap.

If the function fails, the return value is NULL.

AtlLoadSysCursorImage

The AtlLoadSysCursorImage function loads the specified system cursor resource.

HCURSOR AtlLoadSysCursorImage (

_U_STRINGorID cursor, 

    UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE, 

    int cxDesired = 0, 

    int cyDesired = 0

);

Parameters

cursor[in] - This parameter can be one or more of the following values.

Value Meaning

IDC_APPSTARTING Standard arrow and small hourglass

IDC_ARROW Standard arrow

IDC_CROSS Crosshair

IDC_HAND Windows 2000: Hand

IDC_HELP Arrow and question mark

IDC_IBEAM I-beam

IDC_ICON Obsolete for applications marked version 4.0 or later.

IDC_NO Slashed circle

IDC_SIZE Obsolete for applications marked version 4.0 or later. Use IDC_SIZEALL.

IDC_SIZEALL Four-pointed arrow pointing north, south, east, and west

IDC_SIZENESW Double-pointed arrow pointing northeast and southwest

IDC_SIZENS Double-pointed arrow pointing north and south

IDC_SIZENWSE Double-pointed arrow pointing northwest and southeast

IDC_SIZEWE Double-pointed arrow pointing west and east

IDC_UPARROW Vertical arrow

IDC_WAIT Hourglass

fuLoad[in] - See AtlLoadBitmapImage

cxDesired[in] - Specifies the width, in pixels, of the cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CXCURSOR system metric value to set the width. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.

cyDesired[in] - Specifies the height, in pixels, of the cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CYCURSOR system metric value to set the height. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.

Value	Meaning
IDC_APPSTARTING	Standard arrow and small hourglass
IDC_ARROW	Standard arrow
IDC_CROSS	Crosshair
IDC_HAND	Windows 2000: Hand
IDC_HELP	Arrow and question mark
IDC_IBEAM	I-beam
IDC_ICON	Obsolete for applications marked version 4.0 or later.
IDC_NO	Slashed circle
IDC_SIZE	Obsolete for applications marked version 4.0 or later. Use IDC_SIZEALL.
IDC_SIZEALL	Four-pointed arrow pointing north, south, east, and west
IDC_SIZENESW	Double-pointed arrow pointing northeast and southwest
IDC_SIZENS	Double-pointed arrow pointing north and south
IDC_SIZENWSE	Double-pointed arrow pointing northwest and southeast
IDC_SIZEWE	Double-pointed arrow pointing west and east
IDC_UPARROW	Vertical arrow
IDC_WAIT	Hourglass

Return Values

If the function succeeds, the return value is a handle to the system cursor resource.

If the function fails, the return value is NULL.

AtlLoadSysIcon

The AtlLoadSysIcon function loads the specified system cursor resource. This function has been superseded by the AtlLoadSysIconImage function.

HICON AtlLoadSysIcon (

LPCTSTR lpIconName

);

Parameters

lpIconName[in] - See AtlLoadSysIconImage. The MAKEINTRESOURCE macro can be used to create this value.

Return Values

If the function succeeds, the return value is the handle to the specified system bitmap.

If the function fails, the return value is NULL.

AtlLoadSysIconImage

The AtlLoadSysIconImage function loads the specified system icon resource.

HICON AtlLoadSysIconImage (

_U_STRINGorID icon, 

    UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE, 

    int cxDesired = 0, 

    int cyDesired = 0

);

Parameters

icon[in] - This parameter can be one or more of the following values.

Value Description

IDI_APPLICATION Default application icon.

IDI_ASTERISK Same as IDI_INFORMATION.

IDI_ERROR Hand-shaped icon.

IDI_EXCLAMATION Same as IDI_WARNING.

IDI_HAND Same as IDI_ERROR.

IDI_INFORMATION Asterisk icon.

IDI_QUESTION Question mark icon.

IDI_WARNING Exclamation point icon.

IDI_WINLOGO Windows logo icon.

fuLoad[in] - See AtlLoadBitmapImage

cxDesired[in] - Specifies the width, in pixels, of the icon. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CXICON system metric value to set the width. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.

cyDesired[in] - Specifies the height, in pixels, of the icon. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CYICON system metric value to set the height. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.

Value	Description
IDI_APPLICATION	Default application icon.
IDI_ASTERISK	Same as IDI_INFORMATION.
IDI_ERROR	Hand-shaped icon.
IDI_EXCLAMATION	Same as IDI_WARNING.
IDI_HAND	Same as IDI_ERROR.
IDI_INFORMATION	Asterisk icon.
IDI_QUESTION	Question mark icon.
IDI_WARNING	Exclamation point icon.
IDI_WINLOGO	Windows logo icon.

Return Values

If the function succeeds, the return value is a handle to the system icon resource.
If the function fails, the return value is NULL.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

BLACK_BRUSH	Black brush.
DKGRAY_BRUSH	Dark gray brush.
DC_BRUSH	Windows 98/2000: Solid color brush. The default color is white. The color can be changed by using the SetDCBrushColor function. For more information, see the Remarks section.
GRAY_BRUSH	Gray brush.
HOLLOW_BRUSH	Hollow brush (equivalent to NULL_BRUSH).
LTGRAY_BRUSH	Light gray brush.
NULL_BRUSH	Null brush (equivalent to HOLLOW_BRUSH).
WHITE_BRUSH	White brush.

ANSI_FIXED_FONT	Windows fixed-pitch (monospace) system font.
ANSI_VAR_FONT	Windows variable-pitch (proportional space) system font.
DEVICE_DEFAULT_FONT	Windows NT/2000: Device-dependent font.
DEFAULT_GUI_FONT	Default font for user interface objects such as menus and dialog boxes.
OEM_FIXED_FONT	Original equipment manufacturer (OEM) dependent fixed-pitch (monospace) font.
SYSTEM_FONT	System font. By default, the system uses the system font to draw menus, dialog box controls, and text.
SYSTEM_FIXED_FONT	Fixed-pitch (monospace) system font. This stock object is provided only for compatibility with 16-bit Windows versions earlier than 3.0.

NULL_PEN	Null pen.
BLACK_PEN	Black pen.
DC_PEN	Windows 98/2000: Solid pen color. The default color is white. The color can be changed by using the SetDCPenColor function. For more information, see the Remarks section.
WHITE_PEN	White pen.