This documentation is archived and is not being maintained.

CFrameWnd Class

Provides the functionality of a Windows single document interface (SDI) overlapped or pop-up frame window, along with members for managing the window.

class CFrameWnd : public CWnd




Constructs a CFrameWnd object.




Makes the frame visible and available to the user.


Sets the frame window to modal.


Call to create and initialize the Windows frame window associated with the CFrameWnd object.


Creates a view within a frame that is not derived from CView.


Docks a control bar.


Allows a control bar to be docked.


Ends the frame window's modal state. Enables all of the windows disabled by BeginModalState.


Floats a control bar.


Returns the active CDocument object.


Returns the active CFrameWnd object.


Returns the active CView object.


Retrieves the control bar.


Retrieves the dock state of a frame window.


Retrieves the display state of the menu in the current MFC application.


Indicates whether the default behavior of the menu in the current MFC application is either hidden or visible.


Returns a pointer to the status bar belonging to the frame window.


Retrieves message corresponding to a command ID.


Retrieves the title of the related control bar.


Causes the OnInitialUpdate member function belonging to all views in the frame window to be called.


Returns a value indicating whether or not a frame window is in a modal state.


Determines if splitter bar is currently being moved.


Call to load an accelerator table.


Call to restore control bar settings.


Call to dynamically create a frame window from resource information.


Negotiates border space in the frame window.


Called whenever an action is performed on the specified control bar.


Handles SHIFT+F1 Help for in-place items.


Sets the application's main frame window into and out of print-preview mode.


Called by the framework when the associated menu is updated.


Repositions the control bars of the CFrameWnd object.


Call to save control bar settings.


Designates the specified view to be the active view for Rich Preview.


Sets the active CView object.


Call to dock the frame window in the main window.


Sets the display state of the menu in the current MFC application to hidden or displayed.


Sets the default behavior of the menu in the current MFC application to be either hidden or visible.


Sets the text of a standard status bar.


Sets current position for Windows 7 progress bar displayed on taskbar.


Sets range for Windows 7 progress bar displayed on taskbar.


Sets the type and state of the progress indicator displayed on a taskbar button.


Overloaded. Applies an overlay to a taskbar button to indicate application status or a notification to the user.


Sets the title of the related control bar.


Call to show the control bar.


Shows all windows that are descendants of the CFrameWnd object.




Creates a client window for the frame.


Called before the menu in the current MFC application is hidden.


Called before the menu in the current MFC application is displayed.




Controls automatic enable and disable functionality for menu items.


Pass this static CRect as a parameter when creating a CFrameWnd object to allow Windows to choose the window's initial size and position.

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

  • Directly construct it using Create.

  • Directly construct it using LoadFrame.

  • Indirectly construct it using a document template.

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

When a CFrameWnd 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 multiple document interface (MDI) Window New command).

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

A CFrameWnd contains default implementations to perform the following functions of a main window in a typical application for Windows:

  • A CFrameWnd frame window keeps track of a currently active view that is independent of the Windows active window or the current input focus. When the frame is reactivated, the active view is notified by calling CView::OnActivateView.

  • Command messages and many common frame-notification messages, including those handled by the OnSetFocus, OnHScroll, and OnVScroll functions of CWnd, are delegated by a CFrameWnd frame window to the currently active view.

  • The currently active view (or currently active MDI child frame window in the case of an MDI frame) can determine the caption of the frame window. This feature can be disabled by turning off the FWS_ADDTOTITLE style bit of the frame window.

  • A CFrameWnd frame window manages the positioning of the control bars, views, and other child windows inside the frame window's client area. A frame window also does idle-time updating of toolbar and other control-bar buttons. A CFrameWnd frame window also has default implementations of commands for toggling on and off the toolbar and status bar.

  • A CFrameWnd frame window manages the main menu bar. When a pop-up menu is displayed, the frame window uses the UPDATE_COMMAND_UI mechanism to determine which menu items should be enabled, disabled, or checked. When the user selects a menu item, the frame window updates the status bar with the message string for that command.

  • A CFrameWnd frame window has an optional accelerator table that automatically translates keyboard accelerators.

  • A CFrameWnd frame window has an optional help ID set with LoadFrame that is used for context-sensitive help. A frame window is the main orchestrator of semimodal states such as context-sensitive help (SHIFT+F1) and print-preview modes.

  • A CFrameWnd frame window will open a file dragged from the File Manager and dropped on the frame window. If a file extension is registered and associated with the application, the frame window responds to the dynamic data exchange (DDE) open request that occurs when the user opens a data file in the File Manager or when the ShellExecute Windows function is called.

  • If the frame window is the main application window (that is, CWinThread::m_pMainWnd), when the user closes the application, the frame window prompts the user to save any modified documents (for OnClose and OnQueryEndSession).

  • If the frame window is the main application window, the frame window is the context for running WinHelp. Closing the frame window will shut down WINHELP.EXE if it was launched for help for this application.

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

Header: afxwin.h