CMDIFrameWnd Class

Article
12/01/2022

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 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);
}

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

// CMainFrame::OnWindowCommand() is a menu command handler for
// CMainFrame class, which is a CMDIFrameWnd-derived
// class. It handles menu commands for the Windows pop-up menu.
// Its entries in the message map are of the following form:
//    ON_COMMAND_EX(ID_WINDOW_ARRANGE, &CMainFrame::OnWindowCommand)
BOOL CMainFrame::OnWindowCommand(UINT nID)
{
   switch (nID)
   {
   case ID_WINDOW_ARRANGE: // For Window\Arrange Icons menu item, arrange
      MDIIconArrange();    // all minimized document child windows.
      break;

   case ID_WINDOW_CASCADE: // For Window\Cascade menu item, arrange
      MDICascade();        // all the MDI child windows in a cascade format.
      break;

   case ID_WINDOW_TILE_HORZ:       // For Window\Tile Horizontal menu item,
      MDITile(MDITILE_HORIZONTAL); // tile MDI child windows so that
      break;                       // one window appears above another.

   case ID_WINDOW_TILE_VERT:     // For Window\Tile Vertical menu item,
      MDITile(MDITILE_VERTICAL); // tile MDI child windows so that
      break;                     // one window appears beside another.
   }

   return TRUE;
}

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.

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::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.

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

// CMainFrame::OnActivateNextWindow() is a menu command handler for
// CMainFrame class, which in turn is a CMDIFrameWnd-derived class.
// It activates the child window immediately behind the currently
// active child window and places the currently active child window
// behind all other child windows.
void CMainFrame::OnActivateNextWindow()
{
   MDINext();
}

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.

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.

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 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

// CMdiView::OnReplaceMenu() is a menu command handler for CMdiView
// class, which in turn is a CView-derived class. It loads a new
// menu resource and replaces the main application window's menu
// bar with this new menu.
void CMdiView::OnReplaceMenu()
{
   // Load a new menu resource named IDR_SHORT_MENU. m_hDefaultMenu is
   // a member variable of CMdiDoc class (a CDocument-derived class).
   // Its type is HMENU.
   CMdiDoc *pdoc = (CMdiDoc*)GetDocument();
   pdoc->m_hDefaultMenu =
       ::LoadMenu(AfxGetResourceHandle(), MAKEINTRESOURCE(IDR_SHORT_MENU));
   if (pdoc->m_hDefaultMenu == NULL)
      return;

   // Get the parent window of this view window. The parent window is
   // a CMDIChildWnd-derived class. We can then obtain the MDI parent
   // frame window using the CMDIChildWnd*. Then, replace the current
   // menu bar with the new loaded menu resource.
   CMDIFrameWnd *frame = ((CMDIChildWnd*)GetParent())->GetMDIFrame();
   frame->MDISetMenu(CMenu::FromHandle(pdoc->m_hDefaultMenu), NULL);
   frame->DrawMenuBar();
}

// GetDefaultMenu() is an undocumented virtual function for
// CDocument class. It allows the document to determine which
// menu to display. m_hDefaultMenu is of type HMENU. Its value
// is initialized to NULL either in the constructor or
// CDocument::OnNewDocument(). And the menu resource is destroyed
// in the destructor to avoid having too many menus loaded at once.
HMENU CMdiDoc::GetDefaultMenu()
{
   if (m_hDefaultMenu)
      return m_hDefaultMenu;

   return COleServerDoc::GetDefaultMenu();
}

// Initialize member variable(s) in the constructor. CMdiDoc is
// a CDocument-derived class.
CMdiDoc::CMdiDoc()
{
   // Use OLE compound files
   EnableCompoundFile();

   m_hDefaultMenu = NULL; // initialize to NULL
}

// Destroy menu resource in CMdiDoc's destructor. CMdiDoc is
// a CDocument-derived class.
CMdiDoc::~CMdiDoc()
{
   if (m_hDefaultMenu)
      ::DestroyMenu(m_hDefaultMenu);
}

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

CMDIFrameWnd::MDIGetActive

Parameters

Return Value

Example

CMDIFrameWnd::MDIIconArrange

Remarks

Example

CMDIFrameWnd::MDIMaximize

Parameters

Remarks

Example

CMDIFrameWnd::MDINext

Remarks

Example

CMDIFrameWnd::MDIPrev

Remarks

CMDIFrameWnd::MDIRestore

Parameters

Example

CMDIFrameWnd::MDISetMenu

Parameters

Return Value

Remarks

Example

CMDIFrameWnd::MDITile

Parameters

Remarks

Example

See also

Feedback

Feedback

Additional resources