MFC Common Pitfalls

Analogy categoryAnalogies

Overview of Common MFC Pitfalls

MFC (Microsoft Foundation Classes) wraps the Win32 API in a C++ class hierarchy, but that wrapping hides a lot of manual bookkeeping that developers still have to get right by hand. Most production bugs in MFC codebases trace back to a small set of recurring mistakes: broken message maps, dangling window handles, GDI resource leaks, and misuse of the Document/View architecture. Recognizing these patterns early saves days of debugging later.

🏏

Cricket analogy: Just as a captain who ignores field-placement fundamentals concedes easy boundaries over after over, an MFC developer who ignores these recurring mistakes concedes crashes release after release.

Message Map and Handler Mistakes

MFC's message maps (BEGIN_MESSAGE_MAP / END_MESSAGE_MAP with ON_MESSAGE, ON_COMMAND, ON_BN_CLICKED entries) are static tables generated partly by hand and partly by the Class Wizard. A very common pitfall is editing the header declaration of a handler (adding or changing a parameter, or renaming the function) without regenerating the matching macro entry, which either fails to compile or silently never routes the message. Another frequent mistake is forgetting to call the base class handler (e.g. CWnd::OnSize) inside an overridden handler, which breaks default painting, layout, or scrollbar behavior that the framework was quietly relying on.

🏏

Cricket analogy: Forgetting to call the base handler is like a fielder catching the ball but forgetting to relay it back to the keeper — the play looks complete but the run-out chain is broken.

Memory, Handle, and GDI Resource Leaks

MFC wraps raw Win32 resources (HDC, HBITMAP, HPEN, HBRUSH, HFONT) in classes like CDC, CBitmap, CPen, CBrush, and CFont, but these wrappers do not automatically call the matching Delete*() or Release methods for you in every code path — an early return or a thrown exception inside an OnPaint handler can leave a CPen or CBrush selected into a device context and never restored, which leaks a GDI handle every time that code path executes. Because Windows has a hard per-process (and historically per-session) limit on GDI handles, these leaks accumulate silently until the application starts failing to create new brushes, pens, or fonts, often with confusing rendering glitches rather than an obvious crash.

🏏

Cricket analogy: Not restoring the old GDI object into the DC is like a bowler forgetting to hand the ball back to the umpire between overs — eventually someone notices there are too many balls in play and nothing works right.

cpp

// Pitfall: old pen never restored, GDI handle leaks on every WM_PAINT
void CMyView::OnPaint()
{
    CPaintDC dc(this);
    CPen newPen(PS_SOLID, 2, RGB(255, 0, 0));
    CPen* pOldPen = dc.SelectObject(&newPen);
    if (m_bSomeErrorCondition)
    {
        return; // BUG: pOldPen never restored, newPen's destructor
                // deletes a pen still selected into the DC
    }
    dc.Rectangle(0, 0, 100, 100);
    dc.SelectObject(pOldPen); // must run on every path
}

// Fix: guarantee restoration with RAII / scope guard pattern
void CMyView::OnPaint()
{
    CPaintDC dc(this);
    CPen newPen(PS_SOLID, 2, RGB(255, 0, 0));
    CPen* pOldPen = dc.SelectObject(&newPen);
    struct PenRestorer {
        CDC& dc; CPen* old;
        ~PenRestorer() { dc.SelectObject(old); }
    } guard{dc, pOldPen};

    if (m_bSomeErrorCondition)
        return; // guard's destructor still restores the old pen

    dc.Rectangle(0, 0, 100, 100);
}

Document/View Architecture Pitfalls

MFC's Document/View architecture separates data (CDocument) from presentation (CView), synchronized through UpdateAllViews(). A common pitfall is mutating document state directly from a view without calling SetModifiedFlag() and UpdateAllViews(), which leaves the title bar's asterisk, the Save button state, and any secondary views (like a split-window pane) silently out of sync with the actual data. Another frequent mistake is caching a raw pointer to the active document (GetDocument()) across a long-running operation without accounting for the possibility that the user closes the document mid-operation, leading to a use-after-free.

🏏

Cricket analogy: Not calling UpdateAllViews() is like the scoreboard operator updating the paper scorecard but forgetting to update the electronic screen, so the crowd and the official record disagree about the score.

Never assume GetDocument() returns a valid pointer for the lifetime of a long operation. If your view starts an asynchronous task (a worker thread, a modal dialog that pumps messages, or a lengthy loop with PeekMessage), the user can close the document window in the meantime. Re-fetch and re-validate the document pointer, or better, post a custom message back to the main thread once the document's validity has been confirmed.

Editing a handler's signature without regenerating the message map entry causes silent non-routing, not a compile error in many cases.
Forgetting to call the base class handler (e.g. CWnd::OnSize, CWnd::OnPaint) breaks default framework behavior the derived class depends on.
GDI objects selected into a CDC must be restored (SelectObject back to the old object) on every code path, including early returns and exceptions.
Windows enforces a hard per-process GDI handle limit; leaked pens, brushes, and fonts eventually cause silent rendering failures rather than crashes.
Document mutations from a view must call SetModifiedFlag() and UpdateAllViews() to keep the title bar, Save state, and other views synchronized.
Cached CDocument pointers can become dangling if the document closes during a long-running operation; re-validate before use.
Use RAII-style guard objects or try/finally-equivalent patterns to guarantee GDI resource cleanup on every exit path.

Practice what you learned

1. What is the most likely consequence of leaving a CPen selected into a CDC without restoring the previous pen on every code path?

2. Why might editing a message handler's function signature without updating the message map macro fail silently instead of producing a compile error?

3. What must a view do after directly mutating CDocument data to keep the UI consistent?

4. Why is caching a CDocument pointer across a long asynchronous operation risky?

5. Which base class call is commonly forgotten in an overridden OnSize handler, breaking default layout behavior?

Was this page helpful?

Debugging MFC Applications