Theme Aware Controls - 08/03/00
-------------------------------

HOW TO MAKE CONTROLS/WINDOWS THEME AWARE

Here are the high-level steps needed to make a control theme-aware:
    
    Preparation

        a. The control author decides which aspects of the control will be 
           theme aware.  
           
        b. He then divides the control up into 1 or more 
           named theme-aware child parts (drawn shapes with optional text).  

        c. For each part, the author can define 1 or more background images 
           in a single bitmap file.  These difference backgrounds are usually
           associated with different states in the control but don't have to 
           be.  At run time, the appropriate image can be selected using an 
           "iStateId" value as the 1-based index to the correct image.
         
        d. alternatively, the author can decide the create the background based 
           on a border color/style/size and a fill color/style.

        e. other ways of rendering may be defined in the future; try to keep
           your control as isolated as possible from the particular theme properties
           and try to use the theme drawing API's exclusively.

        f. the control author then publishes the theme schema for his control.  If the control is 
           part of comctrls v6, then the schema is added to the file "TmSchema.h"; otherwise,
           the control creates his own "xxxSchema.h" file (which needs to get compiled into
           his control as well as registered with the theme manager).

        g. add schema info:

            - he adds a parts enum to the schema file; ex:

                BEGIN_TM_CLASS_PARTS(EDIT)
                    TM_PART(EP, EDITTEXT)
                    TM_PART(EP, CARET)
                END_TM_CLASS_PARTS()

            - for each part that has more than 1 state, he adds a state enum:

                BEGIN_TM_PART_STATES(EDITTEXT)
                    TM_STATE(ETS, NORMAL)
                    TM_STATE(ETS, HOT)
                    TM_STATE(ETS, SELECTED)
                    TM_STATE(ETS, DISABLED)
                    TM_STATE(ETS, FOCUSED)
                    TM_STATE(ETS, READONLY)
                    TM_STATE(ETS, ASSIST)
                END_TM_PART_STATES()
                    
        h. note that once "TmSchema.h" has been edited, the "\nt\shell\published\inc" directory
           must be built so that the "TmSchema.h" file is copied to "\nt\public\sdk\inc".

    Code Changes

        a. obtain an HTHEME handle to call thememgr drawing routines with.  this should 
               be done during control creation (as soon as the "hwnd" is available).
               The code for the button control would look something like this:

               HTHEME hTheme;
               hTheme = OpenThemeData(hwnd, L"button");
               if (! hTheme)        // fall back on old drawing code...
               {
               }

        b. when its time to paint one of the parts of the control:
        
                i.  first initialize the control's DC; most controls send a WM_CTLCOLORXXX
                    msg to their parent to do this.  Use the HBRUSH returned from the WM_CTLCOLORXXX
                    msg as the DefaultBrush passed to the theme drawing routines.


                ii. pass "hTheme" and the DefaultBrush to the theme drawing routines to paint 
                    the background, text, line, border, etc.  The routines will ensure that the 
                    painting is done in a theme-compliant way.  

               The code for drawing the a push button background would look something like:

                //---- initialize the DC & get DefaultBrush ----
                HBRUSH hDefaultBrush = (HBRUSH)SendMessage(GetParent(hwnd), WM_CTLCOLORBTN, (WPARAM)hdc, (LPARAM)hwnd);

                if (hTheme)
                {            
                    int iStateId;

                    if (fPushed)
                        iStateId = 4;
                    else if (fDisabled)
                        iStateId = 3;
                    else if (fMouseOver)
                        iStateId = 2;
                    else if (fDefault)
                        iStateId = 1;
                    else
                        iStateId = 0;

                    //---- DrawThemeBackground doesn't yet accept the hDefaultBrush param ----
                    hr = DrawThemeBackgound(hTheme, hdc, TMT_BUTTON, iStateId, &clientRect, 0);
                 }
                 else           // old drawing code
                 {
                 }
                
        c. when a WM_THEMECHANGED msg is received by the control/window, it must close its
           current HTMEME handle, try to obtain a new handle, and repaint its control.  
           The code would look something like:

                   CloseThemeData(hTheme);
                   hTheme = OpenThemeData(hwnd, L"BUTTON");
                   InvalidateRect(hwnd, NULL, TRUE);
                    

        d.  The ThemeRender object should be able to handle most or all of the 
            drawing for the control.  However, when the control needs to access 
            some theme information directly, the programmer can pass the "hTheme"
            handle to one of the theme info "getter" routines.  For example, the 
            code to get the FONT for a part would look something like:

                if (hTheme)
                {
                    LOGFONT *pFont;
                    hr = GetThemeFont(hTheme, TMBU_BUTTON, 0, pvFONT, &pFont);
                    if (SUCCEEDED(hr))
                    {
                        <use the pFont here...>
                    }
                }
                 
        e.  Since its possible that the control's main background may contain 
            transparent parts, the programmer will need to handle the WM_NCHITTEST msg 
            processing.  The code would look something like this:

            
                if ((msg == WM_NCHITTEST) && (hTheme))
                {
                    int val = DefWindowProc(msg, hwnd, wparam, lparam);
                    if (val == HTCLIENT)        // test further
                    {
                        BOOL fHit;
                        hr = HitTestThemeBackground(hTheme, hdc, TMBU_BUTTON, 0, iStateIndex, 
                            &clientRect, &fHit);
                        if ((SUCCEEDED(hr)) && (! fHit))
                            val = HTTRANSPARENT;
                    }

                    return val;
                }

        f.   The programmer needs to be aware that being themed can change the size of 
             various parts.  For example, a background that used to have a 2-pixel border 
             around it may now use a 6-pixel border.  The programmer should use methods 
             like "GetThemeBackgroundContentRect()" to determine which parts of the background 
             content can be put into and "GetThemeTextExtent()" to find out how much space 
             the text needs in its theme-selected font.