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.

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

Parameters

nCmdShow
Specifies the parameter to pass to CWnd::ShowWindow. By default, the frame is shown and correctly restored.

Remarks

This member function is usually called after a non-user interface event such as a DDE, OLE, or other event that may show the frame window or its contents to the user.

The default implementation activates the frame and brings it to the top of the Z-order and, if necessary, carries out the same steps for the application's main frame window.

Override this member function to change how a frame is activated. For example, you can force MDI child windows to be maximized. Add the appropriate functionality, then call the base class version with an explicit nCmdShow.

Parameters

lpszClassName
Points to a null-terminated character string that names the Windows class. The class name can be any name registered with the AfxRegisterWndClass global function or the RegisterClass Windows function. If NULL, uses the predefined default CFrameWnd attributes.

lpszWindowName
Points to a null-terminated character string that represents the window name. Used as text for the title bar.

dwStyle
Specifies the window style attributes. Include the FWS_ADDTOTITLE style if you want the title bar to automatically display the name of the document represented in the window.

rect
Specifies the size and position of the window. The rectDefault value allows Windows to specify the size and position of the new window.

pParentWnd
Specifies the parent window of this frame window. This parameter should be NULL for top-level frame windows.

lpszMenuName
Identifies the name of the menu resource to be used with the window. Use MAKEINTRESOURCE if the menu has an integer ID instead of a string. This parameter can be NULL.

pContext
Specifies a pointer to a CCreateContext structure. This parameter can be NULL.

Return Value

Nonzero if initialization is successful; otherwise 0.

Remarks

Construct a CFrameWnd object in two steps. First, invoke the constructor, which constructs the CFrameWnd object, and then call Create, which creates the Windows frame window and attaches it to the CFrameWnd object. Create initializes the window's class name and window name and registers default values for its style, parent, and associated menu.

Use LoadFrame rather than Create to load the frame window from a resource instead of specifying its arguments.

Parameters

pContext
Specifies the type of view and document.

nID
The ID number of a view.

Return Value

Pointer to a CWnd object if successful; otherwise NULL.

Remarks

Use this member function to create "views" that are not CView-derived within a frame. After calling CreateView, you must manually set the view to active and set it to be visible; these tasks are not automatically performed by CreateView.

Return Value

A pointer to the current CView. If there is no current view, returns NULL.

Remarks

This function returns NULL when called for an MDI main frame window ( CMDIFrameWnd). In an MDI application, the MDI main frame window does not have a view associated with it. Instead, each individual child window ( CMDIChildWnd) has one or more associated views. The active view in an MDI application can be obtained by first finding the active MDI child window and then finding the active view for that child window. The active MDI child window can be found by calling the function MDIGetActive or GetActiveFrame as demonstrated in the following:

Parameters

state
Contains the current state of the frame window's control bars upon return.

Remarks

You can then write the contents of CDockState to storage using CDockState::SaveState or Serialize. If you later want to restore the control bars to a previous state, load the state with CDockState::LoadState or Serialize, then call SetDockState to apply the previous state to the frame window's control bars.

Return Value

This method returns one of the following values:

AFX_MBV_KEEPVISIBLE (0x01) - The menu is displayed at all times, and by default does not have the focus.

AFX_MBV_DISPLAYONFOCUS (0x02) - The menu is hidden by default. If the menu is hidden, press the ALT key to display the menu and give it the focus. If the menu is displayed, press the ALT or ESC key to hide it.

AFX_MBV_ DISPLAYONFOCUS (0x02) | AFX_MBV_DISPLAYONF10 (0x04) (bitwise combination (OR)) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it.

Remarks

If a runtime error occurs, this method asserts in Debug mode and raises an exception derived from the CException class.

Parameters

pDoc
Points to the document to which the frame window is associated. Can be NULL.

bMakeVisible
If TRUE, indicates that the frame should become visible and active. If FALSE, no descendants are made visible.

Remarks

This causes all views in that frame window to receive their OnInitialUpdate calls.

Also, if there was not previously an active view, the primary view of the frame window is made active. The primary view is a view with a child ID of AFX_IDW_PANE_FIRST. Finally, the frame window is made visible if bMakeVisible is nonzero. If bMakeVisible is 0, the current focus and visible state of the frame window will remain unchanged. It is not necessary to call this function when using the framework's implementation of File New and File Open.

Remarks

The settings you want to restore must be written to the registry before you call LoadBarState. Write the information to the registry by calling CWinApp::SetRegistryKey. Write the information to the INI file by calling SaveBarState.

Parameters

nIDResource
The ID of shared resources associated with the frame window.

dwDefaultStyle
The frame's style. Include the FWS_ADDTOTITLE style if you want the title bar to automatically display the name of the document represented in the window.

pParentWnd
A pointer to the frame's parent.

pContext
A pointer to a CCreateContext structure. This parameter can be NULL.

Remarks

Construct a CFrameWnd object in two steps. First, invoke the constructor, which constructs the CFrameWnd object, and then call LoadFrame, which loads the Windows frame window and associated resources and attaches the frame window to the CFrameWnd object. The nIDResource parameter specifies the menu, the accelerator table, the icon, and the string resource of the title for the frame window.

Use the Create member function rather than LoadFrame when you want to specify all of the frame window's creation parameters.

The framework calls LoadFrame when it creates a frame window using a document template object.

The framework uses the pContext argument to specify the objects to be connected to the frame window, including any contained view objects. You can set the pContext argument to NULL when you call LoadFrame.

Remarks

statement to your CFrameWnd class message map and also add an accelerator-table entry, typically SHIFT+F1, to enable this member function.

If your application is an OLE Container, OnContextHelp puts all in-place items contained within the frame window object into Help mode. The cursor changes to an arrow and a question mark, and the user can then move the mouse pointer and press the left mouse button to select a dialog box, window, menu, or command button. This member function calls the Windows function WinHelp with the Help context of the object under the cursor.

Parameters

Return Value

Nonzero if successful; otherwise 0.

Remarks

Never call this function.

The default implementation of this function creates a CView object from the information provided in pContext, if possible.

Override this function to override values passed in the CCreateContext object or to change the way controls in the main client area of the frame window are created. The CCreateContext members you can override are described in the CCreateContext class.

Note

Do not replace values passed in the CREATESTRUCT structure. They are for informational use only. If you want to override the initial window rectangle, for example, override the CWnd member function PreCreateWindow.

Remarks

This event handler enables your application to perform custom actions when the system is about to hide the menu. You cannot prevent the menu from being hidden, but you can, for example, call other methods to retrieve the menu style or state.

Parameters

bPreview
Specifies whether or not to place the application in print-preview mode. Set to TRUE to place in print preview, FALSE to cancel preview mode.

pState
A pointer to a CPrintPreviewState structure.

Remarks

The default implementation disables all standard toolbars and hides the main menu and the main client window. This turns MDI frame windows into temporary SDI frame windows.

Override this member function to customize the hiding and showing of control bars and other frame window parts during print preview. Call the base class implementation from within the overridden version.

Remarks

This event handler enables your application to perform custom actions when the menu is about to be displayed. You cannot prevent the menu from being displayed, but you can, for example, call other methods to retrieve the menu style or state.

Parameters

pCmdUI
A pointer to a CCmdUI object representing the menu that generated the update command. The update handler calls the Enable member function of the CCmdUI object through pCmdUI to update the user interface.

Parameters

bNotify
Determines whether the active in-place item for the frame window receives notification of the layout change. If TRUE, the item is notified; otherwise FALSE.

Remarks

The default implementation of this member function calls the CWnd member function RepositionBars to reposition all the control bars in the frame as well as in the main client window (usually a CView or MDICLIENT).

Override this member function to control the appearance and behavior of control bars after the layout of the frame window has changed. For example, call it when you turn control bars on or off or add another control bar.

Parameters

state
Apply the stored state to the frame window's control bars.

Remarks

To restore a previous state of the control bars, you can load the stored state with CDockState::LoadState or Serialize, then use SetDockState to apply it to the frame window's control bars. The previous state is stored in the CDockState object with GetDockState

Parameters

Parameter

Description

[in] nStyle

Specifies whether the menu is by default hidden, or is visible and has the focus. The nStyle parameter can have the following values:

- AFX_MBV_KEEPVISIBLE (0x01) - The menu is displayed at all times, and by default does not have the focus.- AFX_MBV_DISPLAYONFOCUS (0x02) - The menu is hidden by default. If the menu is hidden, press the ALT key to display the menu and give it the focus. If the menu is displayed, press the ALT or ESC key to hide menu.- AFX_MBV_ DISPLAYONFOCUS (0x02) | AFX_MBV_DISPLAYONF10 (0x04) (bitwise combination (OR)) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it.

Remarks

If the value of the nStyle parameter is not valid, this method asserts in Debug mode and raises CInvalidArgException in Release mode. In case of other runtime errors, this method asserts in Debug mode and raises an exception derived from the CException class.

This method affects the state of menus in applications written for Windows Vista and later.

Remarks

Parameters

tbpFlags
Flags that control the current state of the progress button. Specify only one of the following flags because all states are mutually exclusive: TBPF_NOPROGRESS, TBPF_INDETERMINATE, TBPF_NORMAL, TBPF_ERROR, TBPF_PAUSED.

Parameters

nIDResource
Specifies the Resource ID of an icon to use as the overlay. See description for hIcon for details.

lpcszDescr
A pointer to a string that provides an alt text version of the information conveyed by the overlay, for accessibility purposes.

hIcon
The handle of an icon to use as the overlay. This should be a small icon, measuring 16x16 pixels at 96 dots per inch (dpi). If an overlay icon is already applied to the taskbar button, that existing overlay is replaced. This value can be NULL. How a NULL value is handled depends on whether the taskbar button represents a single window or a group of windows. It is the responsibility of the calling application to free hIcon when it is no longer needed.

Return Value

TRUE if successful; FALSE if OS version is less than Windows 7 or if an error occurs setting the icon.