windows-xp/Source/XPSP1/NT/com/oleutest/letest/bttncur/changes.txt

NOTE:  This DLL is the same as that shipped with the OLE 2.0 SDK
but is updated from that shipped with "The Windows Interface" book
from Microsoft Press.  It is now compatible with Windows NT.


----------


Changes in BTTNCUR.DLL Source Code and Documentation from Version 1.00b
to Version 1.1.  See also below for 1.00 to 1.00b changes.

BTTNCUR.DLL version 1.1 is now fully compatible and tested under Windows
3.0.  Previously the demo application crashed under Windows 3.0
on calls to the non-existent MoveToEx (Win32 compatible).  Version 1.1 only
uses MoveToEx for builds where the symbol WINVER < 0x030a.

Windows NT changes are surrounded by #ifdef WIN32.  The largest change
is the DLL entry point:  LibMain.  Both Win3.1 and Win32 versions
call FInitialize now.

The images have been updated slightly and are now provided for 72dpi
(ega), 96dpi (vga), and 120dpi (super vga)

Version 1.1 completely handles system color changes unlike version 1.00x.
This new version will dynamically convert black, light gray, dark gray,
and white pixels in the image bitmap into system colors set for the
button text, button shadow, button face, and button highlight, respectively.
If you have blue, red, yellow, and green button colors, BTTNCUR.DLL will
now work perfectly with all of them.

BTTNCUR.DLL Version 1.1 also supports color images better by allowing
you to control which colors in the image bitmap are converted to system
colors.  By default, any black, gray, or white colors are converted
into system button colors as decribed in the last paragraph.  BTTNCUR.H
defines new PRESERVE_* flags for each of the four colors that are liable
to be converted.  By specifing one or more flags you prevent BTTNCUR
from changing that color to a system color.  For example, if you
want to preserve all black pixels in your image, specify PRESERVE_BLACK
when calling UIToolButtonDraw.

Applications should obtain configuration data for the current display
through UIToolConfigureForDisplay.  With this data the application can
configure itself for the correct toolbar size and button sizes and load
the appropriate application supplied bitmaps.

Applications using UIToolConfigureForDisplay should now use
UIToolButtonDrawTDD instead of UIToolButtonDraw, passing one extra
parameter, a pointer to the TOOLDISPLAYDATA.  Applications that
still call UIToolButtonDraw will always use 96dpi.


------------------------
BTTNCUR.H changes
    Added PRESERVE_ flags to allow application to control color conversions
    from black, dark gray, light gray, and white into the
    file compatible with C++.

    Added prototype for UIToolConfigureForDisplay, TOOLDISPLAYDATA structure,
    and definitions for button and image sizes on 72dpi, 96dpi, and 120dpi.

------------------------
BTTNCUR.RCV version changes
    FILEVERSION and PRODUCTVERSION changed from 1,0,0,2 to 1,0,1,0

    VALUE "FileVersion" and VALUE "ProductVersion" changed from
        "1.00b\0","\0" to "1.1\0","\0"


------------------------
BTTNCURI.H changes
    Defined STDCOLOR_* values as indices into an array in BTTNCUR.C
    that holds hard-coded default button color that never change
    regardless of the system colors.  Also defined SYSCOLOR_*
    flags that matched STDCOLOR_* flags for uniform array indices.

    Removed NEAR, FAR, and PASCAL from any function that didn't need it
    so we can port to Windows NT cleanly.

------------------------
BTTNCUR.C source code changes.  There are significant modifications.

Overall:
    Updated header comment

    Removed NEAR, FAR, and PASCAL from any function that didn't need it
    so we can port to Windows NT cleanly.

Globals:
    Eliminated the COLORREFs prefixed with RGB.  Only a few are needed
    statically and were moved to HBrushDitherCreate.

    Also added an array of standard colors used in the standard images:

    static const
    COLORREF crStandard[4]={ RGB(0, 0, 0)         //STDCOLOR_BLACK
                           , RGB(128, 128, 128)   //STDCOLOR_DKGRAY
                           , RGB(192, 192, 192)   //STDCOLOR_LTGRAY
                           , RGB(255, 255, 255)}; //STDCOLOR_WHITE

    Added an array of standard images instead of just 96dpi versions.

UIToolConfigureForDisplay:
    Added function to return the resolution of the display and
    size information about button and image sizes.


ToolButtonInit():
    Call to CreatePatternBrush moved into HBrushDitherCreate.
    Conditionally sets the highlight color for HDitherBrushCreate
    depending on Windows 3.x or Windows 3.0 (3.0 did not support
    COLOR_BTNHIGHLIGHT).


ToolButtonFree():
    Removed some old debug output no longer useful.


HDitherBitmapCreate()
    Renamed to HBrushDitherCreate.
    Moved CreatePatterBrush code from ToolButtonInit into this
    function.

    To support changing system colors, this function maintains
    static variables for the face and highlight colors that we
    use to create the brush.  If the function is called and the
    current colors in the global hBrushDither are different than
    the system colors, we recreate the brush and update the global
    hBrushDither, deleting the old brush.  Otherwise we just return
    hBrushDither.

    Note that if we fail to create the new brush we just maintain
    the old.  We'll paint something, albeit not in the right colors,
    but something nontheless.


UIToolButtonDraw():
    Calls UIToolButtonDrawTDD with default display configuration.

UIToolButtonDrawTDD():
    This is the function that was overhauled the most, specifically
    to handle variable colors.

    First, we added several local variables of which two are important.
    crSys is an array of system colors for the text, shadow, face,
    highlight, and frame, declared as static to keep references to
    it off DS instead of SS; if it's in SS things will crash.  The second
    important variable is uColor, which receives the color preservation
    flags passed in the hibyte of the uState parameter to UIToolButtonDraw.

    All the code to draw a blank button outline was moved into a separate
    function DrawBlankButton.  Since this procedure needs all the system
    colors to do it's thing, I've set it up to take an array of five
    COLORREFs (exactly crSys) in which it stores those color (it also
    uses it as its color variables).  This way we only have to call
    GetSysColor once for each system color.

    Anything dealing with the dithered brush is moved to the
    BUTTONGROUP_LIGHTFACE case where we just get the current brush
    by calling HBrushDitherCreate, passing it the current face
    and highlight colors.  Remember that is these colors match those
    used in the currently held global hBrushDither, this function just
    returns that global, so it's quite fast.  We have to be very careful
    not to delete this brush where we're done with it since it is global.

    The largest amount of new code is under the line:

    if ((uState & BUTTONGROUP_ACTIVE) && !(uState & BUTTONGROUP_BLANK))

    This has changed from a single BitBlt call to a much more complex
    operation to handle specific color conversions and preservations.
    A little optimization was done to detect when the system colors
    for buttons match the defaults, that is, black, dark gray, light gray,
    and white for text, shadow, face, and highlight.  If these colors
    all match, or if the caller requested preservation of all colors,
    the we just do the single BitBlt of old.

    Otherwise we loop through each of the black/white/gray colors
    that need possible conversion.  For each one we create a mask
    that contains 1's where the converting color exists in the image
    and 0's everywhere else.  For each color then we BitBlt the
    mask, a brush matching the system color we're converting to,
    and the destination bitmap (which we initialize with the unmodified
    image itself) using ROP_DSPDxax.  This leaves any color but the
    one under conversion alone and replaces the converted color with
    the system color.

    If the caller set a specific flag to preserve one or more specific
    colors, then we replace the standard color with the standard color,
    resulting in a no-op.

    Finally, to reduce flicker for this four Blt operation we create
    and build the final image in a temporary bitmap, making it 6 total
    Blts to handle the color changes.  But since we optimized for the
    99% case where the system colors are the standard colors, this isn't
    too much of a consideration.

    color conversions.


DrawBlankButton():
    New internal function.  Moved code from UIToolButtonDraw here.




------------------------
CURSORS.C
    Updated header comment

    Removed PASCAL on both internal functions.


    CursorsFree
        Eliminated all the code inside this function as it was unnecessary.

    UICursorLoad
        Eliminated code to revalidate a cursor in the array.  Unnecessary.


------------------------
BCDEMO.C

    Tested for running under Windows 3.0 and avoided MoveToEx calls,
    using MoveTo instead.  Calling MoveToEx in a Windows 3.1 app
    marked as 3.0 compatible under 3.0 causes an unknown GP fault.

    Uses UIToolButtonConfigureForDisplay and UIToolButtonDrawTDD.


------------------------------------------------------------------------------

Changes in BTTNCUR.DLL Source Code and Documentation from Version 1.00
to Version 1.00b

------------------------
BTTNCUR.H changes
    Added #ifdef __cplusplus to include extern "C" making the
    file compatible with C++.


------------------------
BTTNCURI.H changes
    Added #ifdef __cplusplus to include extern "C" making the
    file compatible with C++.

    Removed code contained between a #ifdef NEVER that is unused.


------------------------
BTTNCUR.RCV version changes
    FILEVERSION and PRODUCTVERSION changed from 1,0,0,0 to 1,0,0,2

    VALUE "FileVersion" and VALUE "ProductVersion" changed from
        "1.00\0","\0" to "1.00b\0","\0"


------------------------
BTTNCUR.C source code changes.

    Added a global for the frame color
    static COLORREF rgbFrame   =RGB(0, 0, 0);

WEP():
    Added comment about resource cleanup messages in DEBUG mode.


ToolButtonInit():
    Added the line below just before the assignment of hDCGlyphs:

        rgbFrame=GetSysColor(COLOR_WINDOWFRAME);

    This insures that the frame color is properly shown on plasma
    displays.


ToolButtonFree():
    Added the following lines just before return:

        if (NULL!=hBmpStandardImages)
            DeleteObject(hBmpStandardImages);
        hBmpStandardImages=NULL;


UIToolButtonDraw():
    The image centering is one too high.  The line 

        yOffsetGlyph=((dy-bmy) >> 1)-1;

    now reads:
   
        yOffsetGlyph=(dy-bmy) >> 1;


    The declaration HBITMAP hBmp; now read HBITMAP hBmp=NULL;

    The line hBmpT=SelectObject(hDCGlyphs, hBmp); is now two:

        if (NULL!=hBmp)
            SelectObject(hDCGlyphs, hBmp);

    The line SelectObject(hDCGlyphs, hBmpT); is now two:

        if (NULL!=hBmpT)
            SelectObject(hDCGlyphs, hBmpT);



------------------------
BTTNCUR.BMP
    Fixed the images to be 16*15 (the standard) instead of 16*16
    as they originally were.  Changed the label "16x16" to "16x15".

    Copied an image of the disabled state of Context-Sensitive Help
    to this bitmap as it was previously missing.