CMDIChildWnd Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CMDIChildWnd Class.

Provides the functionality of a Windows multiple document interface (MDI) child window, along with members for managing the window.

Syntax

class CMDIChildWnd : public CFrameWnd

Members

Public Constructors

Name	Description
CMDIChildWnd::CMDIChildWnd	Constructs a `CMDIChildWnd` object.

Public Methods

Name	Description
CMDIChildWnd::Create	Creates the Windows MDI child window associated with the `CMDIChildWnd` object.
CMDIChildWnd::GetMDIFrame	Returns the parent MDI frame of the MDI client window.
CMDIChildWnd::MDIActivate	Activates this MDI child window.
CMDIChildWnd::MDIDestroy	Destroys this MDI child window.
CMDIChildWnd::MDIMaximize	Maximizes this MDI child window.
CMDIChildWnd::MDIRestore	Restores this MDI child window from maximized or minimized size.
CMDIChildWnd::SetHandles	Sets the handles for menu and accelerator resources.

Remarks

An MDI child window looks much like a typical frame window, except that the MDI child window appears inside an MDI frame window rather than on the desktop. An MDI child window does not have a menu bar of its own, but instead shares the menu of the MDI frame window. The framework automatically changes the MDI frame menu to represent the currently active MDI child window.

To create a useful MDI child window for your application, derive a class from CMDIChildWnd. Add member variables to the derived class to store data specific to your application. Implement message-handler member functions and a message map in the derived class to specify what happens when messages are directed to the window.

There are three ways to construct an MDI child window:

Directly construct it using Create.
Directly construct it using LoadFrame.
Indirectly construct it through a document template.

Before you call Create or LoadFrame, you must construct the frame-window object on the heap using the C++ new operator. Before calling Create you can also register a window class with the [AfxRegisterWndClass]--brokenlink--(../Topic/not%20found.md#afxregisterwndclass) global function to set the icon and class styles for the frame.

Use the Create member function to pass the frame's creation parameters as immediate arguments.

LoadFrame requires fewer arguments than Create, and instead retrieves most of its default values from resources, including the frame's caption, icon, accelerator table, and menu. To be accessible by LoadFrame, all these resources must have the same resource ID (for example, IDR_MAINFRAME).

When a CMDIChildWnd object contains views and documents, they are created indirectly by the framework instead of directly by the programmer. The CDocTemplate object orchestrates the creation of the frame, the creation of the containing views, and the connection of the views to the appropriate document. The parameters of the CDocTemplate constructor specify the CRuntimeClass of the three classes involved (document, frame, and view). A CRuntimeClass object is used by the framework to dynamically create new frames when specified by the user (for example, by using the File New command or the MDI Window New command).

A frame-window class derived from CMDIChildWnd must be declared with DECLARE_DYNCREATE in order for the above RUNTIME_CLASS mechanism to work correctly.

The CMDIChildWnd class inherits much of its default implementation from CFrameWnd. For a detailed list of these features, please refer to the CFrameWnd class description. The CMDIChildWnd class has the following additional features:

In conjunction with the CMultiDocTemplate class, multiple CMDIChildWnd objects from the same document template share the same menu, saving Windows system resources.
The currently active MDI child window menu entirely replaces the MDI frame window's menu, and the caption of the currently active MDI child window is added to the MDI frame window's caption. For further examples of MDI child window functions that are implemented in conjunction with an MDI frame window, see the CMDIFrameWnd class description.

Do not use the C++ delete operator to destroy a frame window. Use CWnd::DestroyWindow instead. The CFrameWnd implementation of PostNcDestroy will delete the C++ object when the window is destroyed. When the user closes the frame window, the default OnClose handler will call DestroyWindow.

For more information on CMDIChildWnd, see Frame Windows.

Inheritance Hierarchy

CMDIChildWnd

Requirements

Header: afxwin.h

CMDIChildWnd::CMDIChildWnd

Call to construct a CMDIChildWnd object.

CMDIChildWnd();

Remarks

Call Create to create the visible window.

Example

See the example for CMDIChildWnd::Create.

CMDIChildWnd::Create

Call this member function to create a Windows MDI child window and attach it to the CMDIChildWnd object.

virtual BOOL Create(
    LPCTSTR lpszClassName,  
    LPCTSTR lpszWindowName,  
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | WS_OVERLAPPEDWINDOW,  
    const RECT& rect = rectDefault,  
    CMDIFrameWnd* pParentWnd = NULL,  
    CCreateContext* pContext = NULL);

Parameters

lpszClassName
Points to a null-terminated character string that names the Windows class (a WNDCLASS structure). The class name can be any name registered with the AfxRegisterWndClass global function. Should be NULL for a standard CMDIChildWnd.

lpszWindowName
Points to a null-terminated character string that represents the window name. Used as text for the title bar.

dwStyle
Specifies the window style attributes. The WS_CHILD style is required.

rect
Contains the size and position of the window. The rectDefault value allows Windows to specify the size and position of the new CMDIChildWnd.

pParentWnd
Specifies the window's parent. If NULL, the main application window is used.

pContext
Specifies a CCreateContext structure. This parameter can be NULL.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The currently active MDI child frame window can determine the caption of the parent frame window. This feature is disabled by turning off the FWS_ADDTOTITLE style bit of the child frame window.

The framework calls this member function in response to a user command to create a child window, and the framework uses the pContext parameter to properly connect the child window to the application. When you call Create, pContext can be NULL.

Example

Example 1:

// CMainFrame::OnFileNewCMdiChildWnd() is a menu command handler for the 
// CMainFrame class, which in turn is a CMDIFrameWnd-derived class.
// It shows the creation of a standard Windows MDI child window using 
// the registered CMDIChildWnd class.  
void CMainFrame::OnFileNewMdiChildWnd()
{
   CMDIChildWnd* pMDIChildWnd = new CMDIChildWnd;
   VERIFY(pMDIChildWnd->Create(
      NULL,                                        // standard CMDIChildWnd class
      _T("My MDIChildWnd"),                        // caption of MDI child window
      WS_CHILD | WS_VISIBLE | WS_OVERLAPPEDWINDOW, // window styles
      rectDefault,                                 // default rectangle size
      this));                                      // parent window; can be NULL

   // the default PostNcDestroy handler will delete this object when destroyed
}

Example

Example 2:

// CMainFrame::OnHello() is a menu command handler for the CMainFrame
// class, which in turn is a CMDIFrameWnd-derived class.
// It shows the creation of a Windows MDI child window using a custom
// window class. The custom window class is registered in 
// CHelloWnd::Create(). CHelloWnd is a CMDIChildWnd-derived class.
void CMainFrame::OnHello()
{
   CHelloWnd *pHelloWnd = new CHelloWnd;
   if (!pHelloWnd->Create(_T("Hello"),
      WS_CHILD | WS_VISIBLE | WS_OVERLAPPEDWINDOW,
      rectDefault, this))
      return;

   // the default PostNcDestroy handler will delete this object when destroyed
}

BOOL CHelloWnd::Create(
   LPCTSTR szTitle, 
   LONG style              /* = 0 */,
   const RECT& rect        /* = rectDefault */,
   CMDIFrameWnd* parent    /* = NULL */)
{
   // Setup the shared menu
   SetHandles(::LoadMenu(AfxGetInstanceHandle(), MAKEINTRESOURCE(IDR_HELLO)),
      NULL);

   // Register a custom WndClass and create a window.
   // This must be done because CHelloWnd has a custom icon.
   LPCTSTR lpszHelloClass =
      AfxRegisterWndClass(CS_HREDRAW | CS_VREDRAW,
      LoadCursor(NULL, IDC_ARROW),
      (HBRUSH) (COLOR_WINDOW+1),
      LoadIcon(AfxGetInstanceHandle(), MAKEINTRESOURCE(IDI_HELLO)));

   return CMDIChildWnd::Create(lpszHelloClass, szTitle, style, rect, parent);
}

CMDIChildWnd::GetMDIFrame

Call this function to return the MDI parent frame.

CMDIFrameWnd* GetMDIFrame();

Return Value

A pointer to the MDI parent frame window.

Remarks

The frame returned is two parents removed from the CMDIChildWnd and is the parent of the window of type MDICLIENT that manages the CMDIChildWnd object. Call the GetParent member function to return the CMDIChildWnd object's immediate MDICLIENT parent as a temporary CWnd pointer.

Example

See the example for CMDIFrameWnd::MDISetMenu.

CMDIChildWnd::MDIActivate

Call this member function to activate an MDI child window independently of the MDI frame window.

void MDIActivate();

Remarks

When the frame becomes active, the child window that was last activated will be activated as well.

Example

See the example for CMDIFrameWnd::GetWindowMenuPopup.

CMDIChildWnd::MDIDestroy

Call this member function to destroy an MDI child window.

void MDIDestroy();

Remarks

The member function removes the title of the child window from the frame window and deactivates the child window.

Example

// CMainFrame::OnCloseWindow() is a menu command handler for
// CMainFrame class, which in turn is a CMDIFrameWnd-derived 
// class. It closes and destroys the current active MDI child window. 
void CMainFrame::OnCloseWindow() 
{
   CMDIChildWnd* child = MDIGetActive();
   if (child)
      child->MDIDestroy();
}

CMDIChildWnd::MDIMaximize

Call this member function to maximize an MDI child window.

void MDIMaximize();

Remarks

When a child window is maximized, Windows resizes it to make its client area fill the client area of the frame window. Windows places the child window's Control menu in the frame's menu bar so that the user can restore or close the child window and adds the title of the child window to the frame-window title.

Example

// CMainFrame::OnMaximizeWindow() is a menu command handler for
// CMainFrame class, which in turn is a CMDIFrameWnd-derived 
// class. It maximizes the current active MDI child window.
void CMainFrame::OnMaximizeWindow() 
{
   BOOL maximized;
   CMDIChildWnd* child = MDIGetActive(&maximized);
   if (child && (!maximized))
      child->MDIMaximize();   // or MDIMaximize(child); 
}

CMDIChildWnd::MDIRestore

Call this member function to restore an MDI child window from maximized or minimized size.

void MDIRestore();

Example

// CMainFrame::OnRestoreWindow() is a menu command handler for
// CMainFrame class, which in turn is a CMDIFrameWnd-derived class.
// It restores the current active MDI child window from maximized 
// or minimized size.
void CMainFrame::OnRestoreWindow() 
{
   BOOL maximized;
   CMDIChildWnd* child = MDIGetActive(&maximized);
   if (child && (maximized || child->IsIconic()))
     child->MDIRestore();     // or MDIRestore(child);
}

CMDIChildWnd::SetHandles

Sets the handles for menu and accelerator resources.

void SetHandles(
    HMENU hMenu,  
    HACCEL hAccel);

Parameters

hMenu
The handle of a menu resource.

hAccel
The handle of an accelerator resource.

Remarks

Call this function to set the menu and accelerator resources used by the MDI child window object.

Share via

CMDIChildWnd Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CMDIChildWnd::CMDIChildWnd

Remarks

Example

CMDIChildWnd::Create

Parameters

Return Value

Remarks

Example

Example

CMDIChildWnd::GetMDIFrame

Return Value

Remarks

Example

CMDIChildWnd::MDIActivate

Remarks

Example

CMDIChildWnd::MDIDestroy

Remarks

Example

CMDIChildWnd::MDIMaximize

Remarks

Example

CMDIChildWnd::MDIRestore

Example

CMDIChildWnd::SetHandles

Parameters

Remarks

See Also

Additional resources