CFrameWnd Class

Article
01/08/2013

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

Members

Public Constructors

Name	Description
CFrameWnd::CFrameWnd	Constructs a CFrameWnd object.

Public Methods

Name	Description
CFrameWnd::ActivateFrame	Makes the frame visible and available to the user.
CFrameWnd::BeginModalState	Sets the frame window to modal.
CFrameWnd::Create	Call to create and initialize the Windows frame window associated with the CFrameWnd object.
CFrameWnd::CreateView	Creates a view within a frame that is not derived from CView.
CFrameWnd::DockControlBar	Docks a control bar.
CFrameWnd::EnableDocking	Allows a control bar to be docked.
CFrameWnd::EndModalState	Ends the frame window's modal state. Enables all of the windows disabled by BeginModalState.
CFrameWnd::FloatControlBar	Floats a control bar.
CFrameWnd::GetActiveDocument	Returns the active CDocument object.
CFrameWnd::GetActiveFrame	Returns the active CFrameWnd object.
CFrameWnd::GetActiveView	Returns the active CView object.
CFrameWnd::GetControlBar	Retrieves the control bar.
CFrameWnd::GetDockState	Retrieves the dock state of a frame window.
CFrameWnd::GetMenuBarState	Retrieves the display state of the menu in the current MFC application.
CFrameWnd::GetMenuBarVisibility	Indicates whether the default behavior of the menu in the current MFC application is either hidden or visible.
CFrameWnd::GetMessageBar	Returns a pointer to the status bar belonging to the frame window.
CFrameWnd::GetMessageString	Retrieves message corresponding to a command ID.
CFrameWnd::GetTitle	Retrieves the title of the related control bar.
CFrameWnd::InitialUpdateFrame	Causes the OnInitialUpdate member function belonging to all views in the frame window to be called.
CFrameWnd::InModalState	Returns a value indicating whether or not a frame window is in a modal state.
CFrameWnd::IsTracking	Determines if splitter bar is currently being moved.
CFrameWnd::LoadAccelTable	Call to load an accelerator table.
CFrameWnd::LoadBarState	Call to restore control bar settings.
CFrameWnd::LoadFrame	Call to dynamically create a frame window from resource information.
CFrameWnd::NegotiateBorderSpace	Negotiates border space in the frame window.
CFrameWnd::OnBarCheck	Called whenever an action is performed on the specified control bar.
CFrameWnd::OnContextHelp	Handles SHIFT+F1 Help for in-place items.
CFrameWnd::OnSetPreviewMode	Sets the application's main frame window into and out of print-preview mode.
CFrameWnd::OnUpdateControlBarMenu	Called by the framework when the associated menu is updated.
CFrameWnd::RecalcLayout	Repositions the control bars of the CFrameWnd object.
CFrameWnd::SaveBarState	Call to save control bar settings.
CFrameWnd::SetActivePreviewView	Designates the specified view to be the active view for Rich Preview.
CFrameWnd::SetActiveView	Sets the active CView object.
CFrameWnd::SetDockState	Call to dock the frame window in the main window.
CFrameWnd::SetMenuBarState	Sets the display state of the menu in the current MFC application to hidden or displayed.
CFrameWnd::SetMenuBarVisibility	Sets the default behavior of the menu in the current MFC application to be either hidden or visible.
CFrameWnd::SetMessageText	Sets the text of a standard status bar.
CFrameWnd::SetProgressBarPosition	Sets current position for Windows 7 progress bar displayed on taskbar.
CFrameWnd::SetProgressBarRange	Sets range for Windows 7 progress bar displayed on taskbar.
CFrameWnd::SetProgressBarState	Sets the type and state of the progress indicator displayed on a taskbar button.
CFrameWnd::SetTaskbarOverlayIcon	Overloaded. Applies an overlay to a taskbar button to indicate application status or a notification to the user.
CFrameWnd::SetTitle	Sets the title of the related control bar.
CFrameWnd::ShowControlBar	Call to show the control bar.
CFrameWnd::ShowOwnedWindows	Shows all windows that are descendants of the CFrameWnd object.

Protected Methods

Name	Description
CFrameWnd::OnCreateClient	Creates a client window for the frame.
CFrameWnd::OnHideMenuBar	Called before the menu in the current MFC application is hidden.
CFrameWnd::OnShowMenuBar	Called before the menu in the current MFC application is displayed.

Public Data Members

Name	Description
CFrameWnd::m_bAutoMenuEnable	Controls automatic enable and disable functionality for menu items.
CFrameWnd::rectDefault	Pass this static CRect as a parameter when creating a CFrameWnd object to allow Windows to choose the window's initial size and position.

Remarks

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.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CFrameWnd

Requirements

Header: afxwin.h