Return to tn003.txt CVS log

Up to [WindowsNT SDKs] / mstools / mfc / doc

Annotation of mstools/mfc/doc/tn003.txt, revision 1.1

1.1     ! root        1: Microsoft Foundation Classes                           Microsoft Corporation
        !             2: Technical Notes            
        !             3: 
        !             4: #3 : Handle Maps
        !             5: 
        !             6: This note describes the MFC routines for supporting mapping Windows object
        !             7: handles to C++ objects.
        !             8: 
        !             9: =============================================================================
        !            10: 
        !            11: The Problem
        !            12: ===========
        !            13: 
        !            14: Windows objects are normally represented by HANDLEs.  The Foundation 
        !            15: classes wrap Windows object handles with C++ objects.  The handle wrapping
        !            16: functions of the Foundation class library provide a way to find the C++
        !            17: object that is wrapping the Windows object with a particular handle.  There
        !            18: are times when a Windows object does not have a C++ wrapper object, however,
        !            19: and at these times a temporary object is created to act as the C++ wrapper.
        !            20: 
        !            21: 
        !            22: The Windows objects that use handle maps are:
        !            23: 
        !            24:     HWND
        !            25:     HDC
        !            26:     HMENU
        !            27:     HPEN
        !            28:     HBRUSH
        !            29:     HFONT
        !            30:     HBITMAP
        !            31:     HPALETTE
        !            32:     HRGN
        !            33: 
        !            34: Given a handle to any of these objects, you can find the Foundation object
        !            35: that wraps the handle by calling the class static function FromHandle.  For
        !            36: example, given an HWND called hWnd
        !            37: 
        !            38:     CWnd::FromHandle(hWnd)
        !            39: 
        !            40: will return a pointer to the CWnd that wraps the hWnd.  If that hWnd
        !            41: does not have a specific wrapper object, then a temporary CWnd is
        !            42: created to wrap the hWnd.  This makes it possible to get a valid C++
        !            43: object from any handle.
        !            44: 
        !            45: =============================================================================
        !            46: Attaching Handles to Foundation Objects
        !            47: =======================================
        !            48: 
        !            49: Given a newly created handle wrapper object and a handle to a Windows object,
        !            50: you can associate the two by calling Attach.  For example:
        !            51: 
        !            52:     CWnd myWnd;
        !            53:     myWnd.Attach(hWnd);
        !            54: 
        !            55: This makes an entry in the permanent map associating myWnd and hWnd.
        !            56: Calling CWnd::FromHandle(hWnd) will now return a pointer to myWnd.
        !            57: 
        !            58: Extending this example, when myWnd is deleted the destructor will
        !            59: automatically destroy the hWnd, by calling the *Windows*
        !            60: DestroyWindow function.  If this is not desired, the hWnd must be
        !            61: detached from myWnd before the myWnd object is destroyed (normally
        !            62: when leaving the scope at which myWnd was defined.  The Detach
        !            63: function does this.
        !            64: 
        !            65:     myWnd.Detach();
        !            66: 
        !            67: 
        !            68: 
        !            69: =============================================================================
        !            70: More About Temporary Objects
        !            71: ============================
        !            72: 
        !            73: Temporary objects are created whenever FromHandle is given a handle
        !            74: that does not already have a wrapper object.  These temporary objects
        !            75: are detached from their handle and deleted by the DeleteTempMap
        !            76: functions.  The default OnIdle processing in CWinApp automatically
        !            77: calls DeleteTempMap for each class that supports temporary handle
        !            78: maps.  This means that you cannot assume a pointer to a temporary
        !            79: object will be valid past the point of exit from the function where
        !            80: the pointer was obtained, as the temporary object will be deleted during
        !            81: the Windows message loop idle time.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.