Download WTL .chm Help file - 70 Kb
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
Windows version helpers
Global functions for loading resources
Global functions for stock GDI objects
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.
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.
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.
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
- 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.
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.
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.
- 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.
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.
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.
- 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.