Share via


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

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

See Also

Reference

CWnd Class

Hierarchy Chart

CWnd Class

CMDIFrameWnd Class

CMDIChildWnd Class

CView Class

CDocTemplate Class

CRuntimeClass Structure