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

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.