CMDIFrameWnd 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 CMDIFrameWnd Class.

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

Syntax

class CMDIFrameWnd : public CFrameWnd

Members

Public Constructors

Name	Description
CMDIFrameWnd::CMDIFrameWnd	Constructs a `CMDIFrameWnd`.

Public Methods

Name	Description
CMDIFrameWnd::CreateClient	Creates a Windows MDICLIENT window for this `CMDIFrameWnd`. Called by the `OnCreate` member function of `CWnd`.
CMDIFrameWnd::CreateNewChild	Creates a new child window.
CMDIFrameWnd::GetWindowMenuPopup	Returns the Window pop-up menu.
CMDIFrameWnd::MDIActivate	Activates a different MDI child window.
CMDIFrameWnd::MDICascade	Arranges all child windows in a cascaded format.
CMDIFrameWnd::MDIGetActive	Retrieves the currently active MDI child window, along with a flag indicating whether or not the child is maximized.
CMDIFrameWnd::MDIIconArrange	Arranges all minimized document child windows.
CMDIFrameWnd::MDIMaximize	Maximizes an MDI child window.
CMDIFrameWnd::MDINext	Activates the child window immediately behind the currently active child window and places the currently active child window behind all other child windows.
CMDIFrameWnd::MDIPrev	Activates the previous child window and places the currently active child window immediately behind it.
CMDIFrameWnd::MDIRestore	Restores an MDI child window from maximized or minimized size.
CMDIFrameWnd::MDISetMenu	Replaces the menu of an MDI frame window, the Window pop-up menu, or both.
CMDIFrameWnd::MDITile	Arranges all child windows in a tiled format.

Remarks

To create a useful MDI frame window for your application, derive a class from CMDIFrameWnd. 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.

You can construct an MDI frame window by calling the Create or LoadFrame member function of CFrameWnd.

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 accessed by LoadFrame, all these resources must have the same resource ID (for example, IDR_MAINFRAME).

Though MDIFrameWnd is derived from CFrameWnd, a frame window class derived from CMDIFrameWnd need not be declared with DECLARE_DYNCREATE.

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

An MDI frame window manages the MDICLIENT window, repositioning it in conjunction with control bars. The MDI client window is the direct parent of MDI child frame windows. The WS_HSCROLL and WS_VSCROLL window styles specified on a CMDIFrameWnd apply to the MDI client window rather than the main frame window so the user can scroll the MDI client area (as in the Windows Program Manager, for example).
An MDI frame window owns a default menu that is used as the menu bar when there is no active MDI child window. When there is an active MDI child, the MDI frame window's menu bar is automatically replaced by the MDI child window menu.
An MDI frame window works in conjunction with the current MDI child window, if there is one. For instance, command messages are delegated to the currently active MDI child before the MDI frame window.
An MDI frame window has default handlers for the following standard Window menu commands:
- ID_WINDOW_TILE_VERT
- ID_WINDOW_TILE_HORZ
- ID_WINDOW_CASCADE
- ID_WINDOW_ARRANGE
An MDI frame window also has an implementation of ID_WINDOW_NEW, which creates a new frame and view on the current document. An application can override these default command implementations to customize MDI window handling.

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 CMDIFrameWnd, see Frame Windows.

Inheritance Hierarchy

CMDIFrameWnd

Requirements

Header: afxwin.h

CMDIFrameWnd::CMDIFrameWnd

Constructs a CMDIFrameWnd object.

CMDIFrameWnd();

Remarks

Call the Create or LoadFrame member function to create the visible MDI frame window.

Example

   // Create main MDI Frame window. CMainFrame is a CMDIFrameWnd-derived 
   // class. The default CFrameWnd::PostNcDestroy() handler will delete this 
   // object when destroyed.
   CMainFrame* pMainFrame = new CMainFrame;

CMDIFrameWnd::CreateClient

Creates the MDI client window that manages the CMDIChildWnd objects.

virtual BOOL CreateClient(
    LPCREATESTRUCT lpCreateStruct,  
    CMenu* pWindowMenu);

Parameters

lpCreateStruct
A long pointer to a CREATESTRUCT structure.

pWindowMenu
A pointer to the Window pop-up menu.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function should be called if you override the OnCreate member function directly.

Example

// The code below is from winmdi.cpp. It shows how to 
// call CMDIFrameWnd::CreateClient(). CMainFrame is a 
// CMDIFrameWnd-derived class.
BOOL CMainFrame::OnCreateClient(LPCREATESTRUCT lpcs, CCreateContext* /*pContext*/)
{
   CMenu* pMenu = NULL;
    if (m_hMenuDefault == NULL)
    {
        // default implementation for MFC V1 backward compatibility
        pMenu = GetMenu();
        ASSERT(pMenu != NULL);
        // This is attempting to guess which sub-menu is the Window menu.
        // The Windows user interface guidelines say that the right-most
        // menu on the menu bar should be Help and Window should be one
        // to the left of that.
        int iMenu = pMenu->GetMenuItemCount() - 2;

        // If this assertion fails, your menu bar does not follow the guidelines
        // so you will have to override this function and call CreateClient
        // appropriately or use the MFC V2 MDI functionality.
        ASSERT(iMenu >= 0);
        pMenu = pMenu->GetSubMenu(iMenu);
        ASSERT(pMenu != NULL);
    }

    return CreateClient(lpcs, pMenu);
}

CMDIFrameWnd::CreateNewChild

Creates a new child window.

CMDIChildWnd* CreateNewChild(
    CRuntimeClass* pClass,  
    UINT nResource,  
    HMENU hMenu = NULL,  
    HACCEL hAccel = NULL);

Parameters

pClass
The run-time class of the child window to be created.

nResource
The ID of shared resources associated with the child window.

hMenu
The child window's menu.

hAccel
The child window's accelerator.

Remarks

Use this function to create child windows of an MDI frame window.

Example

// CMainFrame is a CMDIFrameWnd-derived class,
// OnNewDraw is a menu command handler,
// CDrawFrame is a CMDIChildWnd-derived class.
void CMainFrame::OnNewDraw()
{
   CreateNewChild(RUNTIME_CLASS(CDrawFrame), IDR_DRAW, m_hDrawMenu, 
      m_hDrawAccel);
}

This example is an excerpt from Knowledge Base article Q201045, "HOWTO: Add Multiple Window Types to a Non-Document/View MDI App." Knowledge Base articles are available in the MSDN Library Visual Studio documentation or at https://support.microsoft.com.

CMDIFrameWnd::GetWindowMenuPopup

Call this member function to obtain a handle to the current pop-up menu named "Window" (the pop-up menu with menu items for MDI window management).

virtual HMENU GetWindowMenuPopup(HMENU hMenuBar);

Parameters

hMenuBar
The current menu bar.

Return Value

The Window pop-up menu if one exists; otherwise NULL.

Remarks

The default implementation looks for a pop-up menu containing standard Window menu commands such as ID_WINDOW_NEW and ID_WINDOW_TILE_HORZ.

Override this member function if you have a Window menu that does not use the standard menu command IDs.

Example

// CMainFrame::OnActivateFirstMDIChild() is a menu command handler for
// CMainFrame class, which in turn is a CMDIFrameWnd-derived class.
// It looks for the caption of the first created MDI child window from
// the Window popup menu, and then activate the child window.
void CMainFrame::OnActivateFirstMDIChild() 
{
   // Get handle to the Window pop-up menu.
   CMenu* menubar = GetMenu();
   CMenu* wmenu = CMenu::FromHandle(GetWindowMenuPopup(menubar->GetSafeHmenu()));
   if (wmenu == NULL)
      return;
 
   // Get the caption of the first created MDI child window.
   CString caption;
   if (!wmenu->GetMenuString(AFX_IDM_FIRST_MDICHILD, caption, MF_BYCOMMAND))
      return;

   // Get the actual name of the first created MDI child window by 
   // getting rid of the number and space, e.g. "&1 MDI 1".
   int pos = caption.FindOneOf(_T(" "));
   if (pos == -1)
      return;

   caption = caption.Right(caption.GetLength() - (pos + 1));

   // Get the CWnd* of the first created MDI child window by comparing
   // the caption of each MDI child window in the MDI application. 
   // Activate the first created MDI child window if found.
   CMDIChildWnd* child = MDIGetActive();
   do
   {
      CString str;
      child->GetWindowText(str);
      if (str == caption)
      {
         child->MDIActivate();        // or MDIActivate(child);
         break;
      }

      child = (CMDIChildWnd*) child->GetWindow(GW_HWNDNEXT);
   }
   while (child);
}

CMDIFrameWnd::MDIActivate

Activates a different MDI child window.

void MDIActivate(CWnd* pWndActivate);

Parameters

pWndActivate
Points to the MDI child window to be activated.

Remarks

This member function sends the WM_MDIACTIVATE message to both the child window being activated and the child window being deactivated.

This is the same message that is sent if the user changes the focus to an MDI child window by using the mouse or keyboard.

Note

An MDI child window is activated independently of the MDI frame window. When the frame becomes active, the child window that was last activated is sent a WM_NCACTIVATE message to draw an active window frame and caption bar, but it does not receive another WM_MDIACTIVATE message.

Example

See the example for CMDIFrameWnd::GetWindowMenuPopup.

CMDIFrameWnd::MDICascade

Arranges all the MDI child windows in a cascade format.

void MDICascade();  
void MDICascade(int nType);
```  
  
### Parameters  
 `nType`  
 Specifies a cascade flag. Only the following flag can be specified: `MDITILE_SKIPDISABLED`, which prevents disabled MDI child windows from being cascaded.  
  
### Remarks  
 The first version of `MDICascade`, with no parameters, cascades all MDI child windows, including disabled ones. The second version optionally does not cascade disabled MDI child windows if you specify `MDITILE_SKIPDISABLED` for the `nType` parameter.  
  
### Example  
 [!CODE [NVC_MFCWindowing#17](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#17)]  
  
##  <a name="cmdiframewnd__mdigetactive"></a>  CMDIFrameWnd::MDIGetActive  
 Retrieves the current active MDI child window, along with a flag indicating whether the child window is maximized.

CMDIChildWnd* MDIGetActive(BOOL* pbMaximized = NULL) const;

  
### Parameters  
 *pbMaximized*  
 A pointer to a **BOOL** return value. Set to **TRUE** on return if the window is maximized; otherwise **FALSE**.  
  
### Return Value  
 A pointer to the active MDI child window.  
  
### Example  
 See the example for [CMDIChildWnd::MDIMaximize](../Topic/CMDIChildWnd%20Class.md#cmdichildwnd__mdimaximize).  
  
##  <a name="cmdiframewnd__mdiiconarrange"></a>  CMDIFrameWnd::MDIIconArrange  
 Arranges all minimized document child windows.

void MDIIconArrange();

  
### Remarks  
 It does not affect child windows that are not minimized.  
  
### Example  
 See the example for [CMDIFrameWnd::MDICascade](#cmdiframewnd__mdicascade).  
  
##  <a name="cmdiframewnd__mdimaximize"></a>  CMDIFrameWnd::MDIMaximize  
 Maximizes the specified MDI child window.

void MDIMaximize(CWnd* pWnd);

  
### Parameters  
 `pWnd`  
 Points to the window to maximize.  
  
### Remarks  
 When a child window is maximized, Windows resizes it to make its client area fill the client window. Windows places the child window's Control menu in the frame's menu bar so the user can restore or close the child window. It also adds the title of the child window to the frame-window title.  
  
 If another MDI child window is activated when the currently active MDI child window is maximized, Windows restores the currently active child and maximizes the newly activated child window.  
  
### Example  
 See the example for [CMDIChildWnd::MDIMaximize](../Topic/CMDIChildWnd%20Class.md#cmdichildwnd__mdimaximize).  
  
##  <a name="cmdiframewnd__mdinext"></a>  CMDIFrameWnd::MDINext  
 Activates the child window immediately behind the currently active child window and places the currently active child window behind all other child windows.

void MDINext();

  
### Remarks  
 If the currently active MDI child window is maximized, the member function restores the currently active child and maximizes the newly activated child.  
  
### Example  
 [!CODE [NVC_MFCWindowing#18](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#18)]  
  
##  <a name="cmdiframewnd__mdiprev"></a>  CMDIFrameWnd::MDIPrev  
 Activates the previous child window and places the currently active child window immediately behind it.

void MDIPrev();

  
### Remarks  
 If the currently active MDI child window is maximized, the member function restores the currently active child and maximizes the newly activated child.  
  
##  <a name="cmdiframewnd__mdirestore"></a>  CMDIFrameWnd::MDIRestore  
 Restores an MDI child window from maximized or minimized size.

void MDIRestore(CWnd* pWnd);

  
### Parameters  
 `pWnd`  
 Points to the window to restore.  
  
### Example  
 See the example for [CMDIChildWnd::MDIRestore](../Topic/CMDIChildWnd%20Class.md#cmdichildwnd__mdirestore).  
  
##  <a name="cmdiframewnd__mdisetmenu"></a>  CMDIFrameWnd::MDISetMenu  
 Replaces the menu of an MDI frame window, the Window pop-up menu, or both.

CMenu* MDISetMenu( CMenu* pFrameMenu,
CMenu* pWindowMenu);

  
### Parameters  
 *pFrameMenu*  
 Specifies the menu of the new frame-window menu. If **NULL**, the menu is not changed.  
  
 `pWindowMenu`  
 Specifies the menu of the new Window pop-up menu. If **NULL**, the menu is not changed.  
  
### Return Value  
 A pointer to the frame-window menu replaced by this message. The pointer may be temporary and should not be stored for later use.  
  
### Remarks  
 After calling `MDISetMenu`, an application must call the [DrawMenuBar](../Topic/CWnd%20Class.md#cwnd__drawmenubar) member function of `CWnd` to update the menu bar.  
  
 If this call replaces the Window pop-up menu, MDI child-window menu items are removed from the previous Window menu and added to the new Window pop-up menu.  
  
 If an MDI child window is maximized and this call replaces the MDI frame-window menu, the Control menu and restore controls are removed from the previous frame-window menu and added to the new menu.  
  
 Do not call this member function if you use the framework to manage your MDI child windows.  
  
### Example  
 [!CODE [NVC_MFCWindowing#19](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#19)]  
  
 [!CODE [NVC_MFCWindowing#20](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#20)]  
  
##  <a name="cmdiframewnd__mditile"></a>  CMDIFrameWnd::MDITile  
 Arranges all child windows in a tiled format.

void MDITile();
void MDITile(int nType); ```

Parameters

nType
Specifies a tiling flag. This parameter can be any one of the following flags:

MDITILE_HORIZONTAL Tiles MDI child windows so that one window appears above another.
MDITILE_SKIPDISABLED Prevents disabled MDI child windows from being tiled.
MDITILE_VERTICAL Tiles MDI child windows so that one window appears beside another.

Remarks

The first version of MDITile, without parameters, tiles the windows vertically under Windows versions 3.1 and later. The second version tiles windows vertically or horizontally, depending on the value of the nType parameter.

Example

See the example for CMDIFrameWnd::MDICascade.

CMDIFrameWnd Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CMDIFrameWnd::CMDIFrameWnd

Remarks

Example

CMDIFrameWnd::CreateClient

Parameters

Return Value

Remarks

Example

CMDIFrameWnd::CreateNewChild

Parameters

Remarks

Example

CMDIFrameWnd::GetWindowMenuPopup

Parameters

Return Value

Remarks

Example

CMDIFrameWnd::MDIActivate

Parameters

Remarks

Example

CMDIFrameWnd::MDICascade

Parameters

Remarks

Example

See Also

Additional resources