One of the major changes made to the CWinApp class in MFC 4.0 was caused by the
introduction of the CDocManager class, discussed in Chapter 6 Document/View. In previous
versions of MFC, the CWinApp class itself took care of maintaining all of the document
templates for the application, storing them in a list kept by the m_templateList member. With
MFC 4.0, the CWinApp class now has a CDocManager member which encapsulates this list
and the operations performed on it. As a result, a lot of functionality that once resided in the
CWinApp class now is present in this new class. For backwards compatibility reasons, MFC
retained the syntax by providing wrapper functions which simply call equivalent members of
the CDocManager class.
CWinApp::CWinApp
Description: The constructor of the CWinApp class. The constructor initializes the CWinApp object and attaches it to the MFC framework. Rarely does the programmer need to construct a CWinApp-derived object other than the one generated by AppWizard.
Syntax: public, CWinApp();
Parameters: None.
Returns: Nothing is returned.
See Also: CWinApp::~CWinApp
CWinApp::~CWinApp
Description: The destructor of the CWinApp class. The destructor frees structures allocated for the CWinApp-derived object.
Syntax: public, ~CWinApp();
Parameters: None.
Returns: Nothing is returned.
See Also: CWinApp::CWinApp
CWinApp::AddDocTemplate
Description: Adds a document template to the global list kept by the CDocManager member of the CWinApp class for MFC 4.0 and above, and by the CWinApp class itself for earlier versions of MFC. Document templates are stored in a CPtrList list. As a result, document templates should not be created on the stack, but rather dynamically. This list is used to access all of the current documents and document templates for the application.
Syntax: public, void AddDocTemplate(CDocTemplate* pTemplate);
Parameters:
pTemplate Pointer to a document template - MFC will delete this object automatically.
Returns: Nothing is returned.
See Also: CDocManager class Example:
CMultiDocTemplate* pDocTemplate;
pDocTemplate = new CMultiDocTemplate(
IDR_TESTTYPE,
RUNTIME_CLASS(CTestDoc),
RUNTIME_CLASS(CChildFrame), // custom MDI child frame RUNTIME_CLASS(CTestView));
AddDocTemplate(pDocTemplate);
CWinApp::AddToRecentFileList
Description: Adds a file name to the MRU (Most Recently Used) file list maintained by MFC. This member is called whenever a document is saved. The file names of the most recently opened documents appear as menu commands on the applicationís menu. The list is stored either in the registry or in the applicationís .INI file. MFC uses the
ID_FILE_MRU_FILE1 command as the marker for the beginning of this list. AppWizard puts this command on the File menu, right above the Exit command. When the user selects one of these commands, the associated file is loaded by the appropriate document. The number of files tracked by the MRU list is specified when calling the LoadStdProfileSettings member. This number is 4 by default and can be as high as 16, if desired. The OnUpdateRecentFileMenu member is the command UI handler for the MRU list. The OnOpenRecentFile member is the command handler for the MRU list.
Syntax: public, virtual void AddToRecentFileList(LPCTSTR lpszPathName);
Parameters:
lpszPathName File name which is to be added to the MRU list.
Returns: Nothing is returned.
See Also: CWinApp::LoadStdProfileSettings, CWinApp::OnUpdateRecentFileMenu, CWinApp::OnOpenRecentFile
Example:
void SaveFile(CMyDocument* pDocument) {
ASSERT(pDocument);
CString strFileName = pDocument->GetPathName();
pDocument->DoMySave(); // perform custom save if ( !strFileName.IsEmpty() )
{
// add to MRU
AfxGetApp()->AddToRecentFileList(strFileName);
} }
CWinApp::AssertValid
Description: Validates the object. This function calls the inherited version from CWinThread and checks the validity of internal members of the CWinApp object. For more information regarding object validation, see Chapter 15 Debugging and Exception Handling.
Syntax: public, virtual void AssertValid() const;
Parameters: None.
Returns: Nothing is returned.
See Also: CWinApp::Dump, CWinThead::AssertValid Example:
void CheckApplication() {
AfxGetApp()->AssertValid();
}
CWinApp::CloseAllDocuments
Description: Closes all documents for the application. A call to this function in turn calls the CloseAllDocuments member of each document template of the application. The CloseAllDocuments member of the document template calls OnCloseDocument for each currently opened document. This function is called by MFC when the main frame window closes.
Syntax: public, void CloseAllDocuments(BOOL bEndSession);
Parameters:
bEndSession TRUE if Windows is terminating; FALSE otherwise.
Returns: Nothing is returned.
See Also: CDocManager::CloseAllDocuments
CWinApp::CreateInitialDocument
Description: Creates an initial document in response to an Apple launching event. This member is only present for Macintosh applications.
Syntax: public, virtual BOOL CreateInitialDocument();
Parameters: None.
Returns: TRUE if successful; FALSE otherwise.
See Also: CWinApp::OnFileNew
CWinApp::CreatePrinterDC
Description: Creates a compatible DC for the currently selected printer.
Syntax: public, BOOL CreatePrinterDC(CDC& dc);
Parameters:
dc Reference to device context.
Returns: TRUE if successful; FALSE otherwise.
See Also: CWinApp::SelectPrinter, CWinApp::GetPrinterDeviceDefaults Example:
CDC dc;
if ( AfxGetApp()->CreatePrinterDC(dc) ) {
CWinApp::DevModeChange
Description: Processes changes to devices like printers. This function is called by CWnd::OnDevModeChange, which is the default handler for the WM_DEVMODECHANGE message. The CWinApp class caches the device parameters of the current printer. The DevModeChange function updates this cache.
Syntax: public, void DevModeChange(LPTSTR lpDeviceName);
Parameters:
lpDeviceName Name for device changed.
Returns: Nothing is returned.
See Also: CWinApp::UpdatePrinterSelection
CWinApp::DoMessageBox
Description: Displays a message box. This function is called by AfxMessageBox. It may be overridden by a CWinApp-derived class to provide a custom message box display. DoMessageBox sets up a help context, specifies an appropriate icon, and disables any OLE-based modeless windows before calling the SDK function MessageBox.
Syntax: public, virtual int DoMessageBox(LPCTSTR lpszPrompt, UINT nType, UINT nIDPrompt);
Parameters:
lpszPrompt Text of the message.
nType Combination of one or more message styles defined in the SDK that specify the appearance and options of the message box.
nIDPrompt Index for the help context link for the message box.
Returns: The value returned by ::MessageBox, the ID value of the button pressed to dismiss the message box.
See Also: AfxMessageBox, CWnd::MessageBox Example:
BOOL ConfirmDelete() {
CString strText = ìAre you sure you want to delete the file?î;
if ( AfxGetApp()->DoMessageBox(strText,MB_YESNO) != MB_NO ) return FALSE;
return TRUE;
}
CWinApp::DoPrintDialog
Description: Internal MFC function for displaying a CPrintDialog dialog and caching the printer values selected. This function is called by OnFilePrintSetup. It is rarely called by the programmer directly.
Syntax: public, int DoPrintDialog(CPrintDialog* pPD);
Parameters:
pPD Pointer to the CPrintDialog object.
Returns: Response from the call to DoModal() made for the CPrintDialog object. See the CPrintDialog class for details.
See Also: CWinApp::OnFilePrintSetup, CWinApp::UpdatePrinterSelection
CWinApp::DoPromptFileName
Description: Requests a file name from the user, used for opening and saving a document. This is a helper function for using the CFileDialog class, discussed in Chapter 8 Dialog Boxes. This function is called by MFC when opening and saving documents.
Syntax: public, BOOL DoPromptFileName(CString& fileName, UINT nIDSTitle, DWORD lFlags, BOOL bOpenFileDialog, CDocTemplate* pTemplate);
Parameters:
fileName Reference to file name specified by the user.
nIDSTitle String resource ID for title of dialog.
lFlags Flags for dialog; see CFileDialog for details.
bOpenFileDialog TRUE if for File Open; FALSE for Save As.
pTemplate Pointer to document template associated with file, NULL indicates all document templates are available. MFC will fill up the File Type list in the dialog with the file types associated with each document template, including the default ì*.*î.
Returns: TRUE if CFileDialog dialog dismissed by OK button (IDOK); FALSE otherwise.
See Also: CFileDialog class Example:
// MFC code
void CDocManager::OnFileOpen() {
// prompt the user (with all document templates) CString newName;
if (!DoPromptFileName(newName, AFX_IDS_OPENFILE, OFN_HIDEREADONLY | OFN_FILEMUSTEXIST, TRUE, NULL))
return; // open cancelled AfxGetApp()->OpenDocumentFile(newName);
// if returns NULL, the user has already been alerted }
CWinApp::DoWaitCursor
Description: Displays or restores from the wait (hour glass) cursor. MFC keeps a counter for the wait cursor. When it is positive, the wait cursor is displayed; otherwise the old cursor is restored. With MFC 4.0, there is now a CWaitCursor class that calls DoWaitCursor in a more object-oriented manner. This function can be overridden by CWinApp-derived classes to modify default behavior. When DoWaitCursor is called to set the wait cursor, MFC keeps track of the old cursor. Be careful not to call DoWaitCursor to decrement the wait cursor counter when there is no old cursor; the cursor will disappear!
Syntax: public, virtual void DoWaitCursor(int nCode);
Parameters:
nCode 1 - increment the wait cursor counter, display the wait cursor.
0 - display the wait cursor, but do not increment the counter (will only display if the counter is positive).
-1 - decrement the wait cursor counter.
Returns: Nothing is returned.
See Also: CWaitCursor class Example:
AfxGetApp()->DoWaitCursor(1);
// do some long process AfxGetApp()->DoWaitCursor(-1);