Click here to Skip to main content
15,867,568 members
Articles / Desktop Programming / WTL
Article

WTL Documented

Rate me:
Please Sign up or sign in to vote.
2.75/5 (5 votes)
1 Jun 2000 134.4K   2.8K   56   8
Beginning Documentation on WTL
  • 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

    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,<br>
        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, <br>
        UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE,<br>
        int cxDesired = 0,<br>
        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, <br>
        UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE, <br>
        int cxDesired = 0, <br>
        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, <br>
        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, <br>
        LPTSTR lpBuffer, <br>
        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, <br>
        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.

    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, <br>
        UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE, <br>
        int cxDesired = 0, <br>
        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.

    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, <br>
        UINT fuLoad = LR_DEFAULTCOLOR | LR_DEFAULTSIZE, <br>
        int cxDesired = 0, <br>
        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.

    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


    Written By
    Team Leader Farmer's Edge
    Canada Canada
    Ben was born in New Zealand and grew up in Mexico; however, he has lived in Canada for most of his adult life. He has traveled to a few places in Canada so far: British Columbia, Saskatchewan, Manitoba, Ontario and Nova Scotia, but has only ever lived in Alberta — all over Alberta. From Lethbridge to Calgary to Fort McMurray: he has seen most of what the province has to offer. He has also left the comfort of his—at the time—home country and gone abroad. In recent history he has been in China, New Zealand, the US, Central America and back to Canada (where he now resides).

    He completed a degree at the University of Lethbridge, in Computer Science; worked for the University of Wisconsin-Madison in the Computer Sciences Department as a Systems Programmer for the Condor Research Project[^]; and is currently completing another degree at the University of Lethbridge, once again, in Computer Science.

    Ben has been known to enjoy reading, watching movies, playing console games, and learning everything he can about computers. And, more importantly, with regards to his character: does not usually speaks about himself in the third person.

    Comments and Discussions

     
    GeneralWTL Alert ! Part 2 Pin
    Daz Richards2-Jun-00 11:25
    Daz Richards2-Jun-00 11:25 
    GeneralRe: WTL Alert ! Part 2 Pin
    Ramon Smits3-Jun-00 7:20
    Ramon Smits3-Jun-00 7:20 
    GeneralRe: WTL Alert ! Part 2 Pin
    27-Jun-01 5:57
    suss27-Jun-01 5:57 
    GeneralWTL7.0 Pin
    Aldamo21-Dec-02 20:58
    Aldamo21-Dec-02 20:58 

    General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

    Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.