CWinApp 类

派生出 Windows 应用程序对象的基类。

语法

class CWinApp : public CWinThread

成员

公共构造函数

名称	描述
CWinApp::CWinApp	构造 CWinApp 对象。

公共方法

名称	描述
CWinApp::AddDocTemplate	将文档模板添加到应用程序的可用文档模板列表中。
CWinApp::AddToRecentFileList	将文件名添加到最近使用的 (MRU) 文件列表。
CWinApp::ApplicationRecoveryCallback	在应用程序意外退出时由框架调用。
CWinApp::CloseAllDocuments	关闭所有打开的文档。
CWinApp::CreatePrinterDC	创建打印机设备上下文。
CWinApp::DelRegTree	删除指定的项及其所有子项。
CWinApp::DoMessageBox	为应用程序实现 AfxMessageBox。
CWinApp::DoWaitCursor	打开和关闭等待光标。
CWinApp::EnableD2DSupport	启用应用程序 D2D 支持。 在初始化主窗口之前调用此方法。
CWinApp::EnableHtmlHelp	为应用程序实现 HTMLHelp，而不是 WinHelp。
CWinApp::EnableTaskbarInteraction	启用任务栏交互。
CWinApp::ExitInstance	进行替代，以在应用程序终止时进行清理。
CWinApp::GetApplicationRecoveryParameter	检索应用程序恢复方法的输入参数。
CWinApp::GetApplicationRecoveryPingInterval	返回重启管理器等待恢复回调函数返回的时长。
CWinApp::GetApplicationRestartFlags	返回重启管理器的标志。
CWinApp::GetAppRegistryKey	返回 HKEY_CURRENT_USER\"Software"\RegistryKey\ProfileName 的项。
CWinApp::GetDataRecoveryHandler	获取应用程序的此实例的数据恢复处理程序。
CWinApp::GetFirstDocTemplatePosition	检索第一个文档模板的位置。
CWinApp::GetHelpMode	检索应用程序使用的帮助的类型。
CWinApp::GetNextDocTemplate	检索文档模板的位置。 可以递归方式使用。
CWinApp::GetPrinterDeviceDefaults	检索打印机设备默认值。
CWinApp::GetProfileBinary	从应用程序的 .INI 文件中的条目中检索二进制数据。
CWinApp::GetProfileInt	从应用程序的 .INI 文件中的条目中检索整数。
CWinApp::GetProfileString	从应用程序的 .INI 文件中的条目中检索字符串。
CWinApp::GetSectionKey	返回 HKEY_CURRENT_USER\"Software"\RegistryKey\AppName\lpszSection 的项。
CWinApp::HideApplication	关闭所有文档之前隐藏应用程序。
CWinApp::HtmlHelp	调用 Windows 函数 HTMLHelp。
CWinApp::InitInstance	替代以执行 Windows 实例初始化，例如创建窗口对象。
CWinApp::IsTaskbarInteractionEnabled	指示是否启用了 Windows 7 任务栏交互。
CWinApp::LoadCursor	加载光标资源。
CWinApp::LoadIcon	加载图标资源。
CWinApp::LoadOEMCursor	加载 OCR_ 常量在 WINDOWS.H 中指定的 Windows OEM 预定义光标。
CWinApp::LoadOEMIcon	加载 OIC_ 常量在 WINDOWS.H 中指定的 Windows OEM 预定义图标。
CWinApp::LoadStandardCursor	加载 IDC_ 常量在 WINDOWS.H 中指定的 Windows 预定义光标。
CWinApp::LoadStandardIcon	加载 IDI_ 常量在 WINDOWS.H 中指定的 Windows 预定义图标。
CWinApp::OnDDECommand	由框架调用来响应动态数据交换 (DDE) execute 命令。
CWinApp::OnIdle	替代以执行特定于应用程序的空闲时间处理。
CWinApp::OpenDocumentFile	由框架调用以从文件打开文档。
CWinApp::ParseCommandLine	分析命令行中的单个参数和标志。
CWinApp::PreTranslateMessage	在将窗口消息发送到 Windows 函数 TranslateMessage 和 DispatchMessage 之前，对这些消息进行筛选。
CWinApp::ProcessMessageFilter	在某些消息到达应用程序之前截获这些消息。
CWinApp::ProcessShellCommand	处理命令行参数和标志。
CWinApp::ProcessWndProcException	截获由应用程序的消息和命令处理程序引发的所有未经处理的异常。
CWinApp::Register	执行自定义注册。
CWinApp::RegisterWithRestartManager	将应用程序注册到重启管理器。
CWinApp::ReopenPreviousFilesAtRestart	确定重启管理器是否重新打开在应用程序意外退出时打开的文件。
CWinApp::RestartInstance	处理由重启管理器发起的应用程序重启。
CWinApp::RestoreAutosavedFilesAtRestart	确定重启管理器在重启应用程序时是否还原自动保存的文件。
CWinApp::Run	运行默认消息循环。 替代以自定义消息循环。
CWinApp::RunAutomated	针对 /Automation 选项测试应用程序的命令行。 已过时。 请改为在调用 ParseCommandLine 之后使用 CCommandLineInfo::m_bRunAutomated 中的值。
CWinApp::RunEmbedded	针对 /Embedding 选项测试应用程序的命令行。 已过时。 请改为在调用 ParseCommandLine 之后使用 CCommandLineInfo::m_bRunEmbedded 中的值。
CWinApp::SaveAllModified	提示用户保存所有已修改的文档。
CWinApp::SelectPrinter	通过“打印”对话框选择用户先前指示的打印机。
CWinApp::SetHelpMode	设置和初始化应用程序使用的帮助类型。
CWinApp::SupportsApplicationRecovery	确定重启管理器是否恢复意外退出的应用程序。
CWinApp::SupportsAutosaveAtInterval	确定重启管理器是否按定期间隔自动保存打开的文档。
CWinApp::SupportsAutosaveAtRestart	确定重启管理器是否在应用程序重启时自动保存任何打开的文档。
CWinApp::SupportsRestartManager	确定应用程序是否支持重启管理器。
CWinApp::Unregister	取消注册已知要由 CWinApp 对象注册的所有内容。
CWinApp::WinHelp	调用 Windows 函数 WinHelp。
CWinApp::WriteProfileBinary	将二进制数据写入应用程序的 .INI 文件中的条目。
CWinApp::WriteProfileInt	将整数写入应用程序的 .INI 文件中的条目。
CWinApp::WriteProfileString	将字符串写入应用程序的 .INI 文件中的条目。

受保护方法

名称	描述
CWinApp::EnableShellOpen	支持用户通过 Windows 文件管理器打开数据文件。
CWinApp::LoadStdProfileSettings	加载标准 .INI 文件设置并启用 MRU 文件列表功能。
CWinApp::OnContextHelp	处理应用程序中的 Shift+F1 帮助。
CWinApp::OnFileNew	实现 ID_FILE_NEW 命令。
CWinApp::OnFileOpen	实现 ID_FILE_OPEN 命令。
CWinApp::OnFilePrintSetup	实现 ID_FILE_PRINT_SETUP 命令。
CWinApp::OnHelp	处理应用程序中的 F1 帮助（使用当前上下文）。
CWinApp::OnHelpFinder	处理 ID_HELP_FINDER 和 ID_DEFAULT_HELP 命令。
CWinApp::OnHelpIndex	处理 ID_HELP_INDEX 命令，并提供默认帮助主题。
CWinApp::OnHelpUsing	处理 ID_HELP_USING 命令。
CWinApp::RegisterShellFileTypes	将应用程序的所有文档类型注册到 Windows 文件管理器。
CWinApp::SetAppID	显式设置应用程序的应用程序用户模型 ID。 应在向用户显示任何用户界面之前调用此方法（最佳位置是应用程序构造函数）。
CWinApp::SetRegistryKey	导致应用程序设置存储在注册表中，而不是 .INI 文件中。
CWinApp::UnregisterShellFileTypes	取消应用程序的所有文档类型到 Windows 文件管理器的注册。

公共数据成员

“属性”	描述
CWinApp::m_bHelpMode	指示用户是否处于帮助上下文模式（通常使用 Shift+F1 调用）。
CWinApp::m_eHelpType	指定应用程序使用的帮助的类型。
CWinApp::m_hInstance	标识应用程序的当前实例。
CWinApp::m_lpCmdLine	指向指定应用程序的命令行的以 null 结尾的字符串。
CWinApp::m_nCmdShow	指定最初如何显示窗口。
CWinApp::m_pActiveWnd	当 OLE 服务器处于就地活动状态时，指向容器应用程序的主窗口的指针。
CWinApp::m_pszAppID	应用程序用户模型 ID。
CWinApp::m_pszAppName	指定应用程序的名称。
CWinApp::m_pszExeName	应用程序的模块名称。
CWinApp::m_pszHelpFilePath	指向应用程序帮助文件的路径。
CWinApp::m_pszProfileName	应用程序的 .INI 文件名。
CWinApp::m_pszRegistryKey	用于确定用来存储应用程序配置文件设置的完整注册表项。

受保护的数据成员

名称	描述
CWinApp::m_dwRestartManagerSupportFlags	用于确定重启管理器行为的标志。
CWinApp::m_nAutosaveInterval	自动保存的间隔时长（毫秒）。
CWinApp::m_pDataRecoveryHandler	指向应用程序的数据恢复处理程序的指针。

备注

应用程序对象提供成员函数，用于初始化应用程序（及其每个实例）和运行应用程序。

使用 Microsoft 基础类的每个应用程序只能包含一个派生自 CWinApp 的对象。 在构造其他 C++ 全局对象时会构造此对象，它在 Windows 调用 WinMain 函数时已可用，其中该函数由 Microsoft 基础类库提供。 在全局级别声明派生的 CWinApp 对象。

从 CWinApp 中派生应用程序类时，替代 InitInstance 成员函数来创建应用程序的主窗口对象。

除了 CWinApp 成员函数之外，Microsoft 基础类库还提供以下全局函数来访问 CWinApp 对象和其他全局信息：

• AfxGetApp 获取指向 CWinApp 对象的指针。

• AfxGetInstanceHandle 获取当前应用程序实例的句柄。

• AfxGetResourceHandle 获取应用程序资源的句柄。

• AfxGetAppName 获取指向包含应用程序名称的字符串的指针。 或者，如果具有指向 CWinApp 对象的指针，则使用 m_pszExeName 获取应用程序的名称。

有关 CWinApp 类的详细信息（包括下列内容的概述），请参阅 CWinApp：应用程序类：

• 应用程序向导编写的派生自 CWinApp 的代码。

• CWinApp 在应用程序执行序列中的角色。

• CWinApp 的默认成员函数实现。

• CWinApp 的可重写项。

m_hPrevInstance 数据成员不复存在。 若要确定正在运行应用程序的另一个实例是否，请使用命名互斥体。 如果互斥体打开失败，则应用程序的其他实例都未在运行。

继承层次结构

CObject

CCmdTarget

CWinThread

CWinApp

要求

标头：afxwin.h

CWinApp::AddDocTemplate

调用此成员函数，将文档模板添加到应用程序维护的可用文档模板列表中。

void AddDocTemplate(CDocTemplate* pTemplate);

参数

pTemplate
指向要添加的 CDocTemplate 的指针。

注解

调用 RegisterShellFileTypes 之前，应将所有文档模板添加到应用程序。

示例

// The following code is produced by the Application Wizard when you
// choose the MDI (multiple document interface) option.
CMultiDocTemplate *pDocTemplate;
pDocTemplate = new CMultiDocTemplate(IDR_MYTYPE,
                                     RUNTIME_CLASS(CMyDoc),
                                     RUNTIME_CLASS(CChildFrame), // custom MDI child frame
                                     RUNTIME_CLASS(CMyView));
if (!pDocTemplate)
   return FALSE;
AddDocTemplate(pDocTemplate);

CWinApp::AddToRecentFileList

调用此成员函数，将 lpszPathName 添加到 MRU 文件列表。

virtual void AddToRecentFileList(LPCTSTR lpszPathName);

参数

lpszPathName
文件的路径。

备注

在使用 LoadStdProfileSettings 成员函数之前，应调用此成员函数来加载当前的 MRU 文件列表。

当框架打开文件，或者执行“另存为”命令使用新名称保存文件时，会调用此成员函数。

示例

// This adds the pathname c:\temp\test.doc to the top of
// the most recently used (MRU) list in the File menu.
AfxGetApp()->AddToRecentFileList(_T("c:\\temp\\test.doc"));

CWinApp::ApplicationRecoveryCallback

在应用程序意外退出时由框架调用。

virtual DWORD ApplicationRecoveryCallback(LPVOID lpvParam);

参数

lpvParam
[in] 保留供将来使用。

返回值

如果此方法成功，则返回 0；如果发生错误，则返回非零值。

备注

如果应用程序支持重启管理器，则框架会在应用程序意外退出时调用此函数。

ApplicationRecoveryCallback 的默认实现使用 CDataRecoveryHandler 将当前打开的文档列表保存到注册表。 此方法不会自动保存任何文件。

若要自定义行为，请在派生的 CWinApp 类中替代此函数，或者将你自己的应用程序恢复方法作为参数传递至 CWinApp::RegisterWithRestartManager。

CWinApp::CloseAllDocuments

调用此成员函数，在退出之前关闭所有打开的文档。

void CloseAllDocuments(BOOL bEndSession);

参数

bEndSession
指定是否正在结束 Windows 会话。 如果正在结束会话，则为 TRUE；否则为 FALSE。

注解

在调用 CloseAllDocuments 之前先调用 HideApplication。

CWinApp::CreatePrinterDC

调用此成员函数，从所选打印机创建打印机设备上下文 (DC)。

BOOL CreatePrinterDC(CDC& dc);

参数

dc
对打印机设备上下文的引用。

返回值

如果成功创建打印机设备上下文，则为非零值；否则为 0。

备注

CreatePrinterDC 会初始化通过引用传入的设备上下文，以便你可使用它进行打印。

如果函数成功，则在完成打印时，必须销毁设备上下文。 可以让 CDC 对象的析构函数执行该操作，也可通过调用 CDC::DeleteDC 显式执行此操作。

CWinApp::CWinApp

构造一个 CWinApp 对象，并传递要存储为应用程序名称的 lpszAppName。

CWinApp(LPCTSTR lpszAppName = NULL);

参数

lpszAppName
一个以 null 结尾的字符串，其中包含 Windows 使用的应用程序名称。 如果未提供此参数，或者它是 NULL，CWinApp 使用资源字符串 AFX_IDS_APP_TITLE 或可执行文件的文件名。

备注

应构造 CWinApp 派生的类的一个全局对象。 应用程序中只能有一个 CWinApp 对象。 构造函数会存储指向 CWinApp 对象的指针，以便 WinMain 可调用该对象的成员函数来初始化和运行应用程序。

CWinApp::DelRegTree

删除特定注册表项及其所有子项。

LONG DelRegTree(
    HKEY hParentKey,
    const CString& strKeyName);

LONG DelRegTree(
    HKEY hParentKey,
    const CString& strKeyName,
    CAtlTransactionManager* pTM = NULL);

参数

hParentKey
注册表项的句柄。

strKeyName
要删除的注册表项的名称。

pTM
指向 CAtlTransactionManager 对象的指针。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。 如果函数失败，则返回值为 Winerror.h 中定义的非零错误代码。

备注

调用此函数以删除指定的项及其子项。

CWinApp::DoMessageBox

框架调用此成员函数来实现全局函数 AfxMessageBox 的消息框。

virtual int DoMessageBox(
    LPCTSTR lpszPrompt,
    UINT nType,
    UINT nIDPrompt);

参数

lpszPrompt
消息框中的文本的地址。

nType
消息框样式。

nIDPrompt
帮助上下文字符串的索引。

返回值

返回与 AfxMessageBox 相同的值。

备注

请勿调用此成员函数来打开消息框；请改用 AfxMessageBox。

替代此成员函数来自定义 AfxMessageBox 调用的应用程序范围处理。

CWinApp::DoWaitCursor

此成员函数由框架调用来实现 CWaitCursor、CCmdTarget::BeginWaitCursor、CCmdTarget::EndWaitCursor 和 CCmdTarget::RestoreWaitCursor。

virtual void DoWaitCursor(int nCode);

参数

nCode
如果此参数为 1，会显示等待光标。 如果为 0，则还原等待光标而不递增引用计数。 如果为 -1，则等待光标结束。

注解

默认是实现沙漏光标。 DoWaitCursor 维护引用计数。 该计数为正时，显示沙漏光标。

虽然通常不会直接调用 DoWaitCursor，但可替代此成员函数来更改等待光标，或者在显示等待光标时执行其他处理。

为了更轻松、更简化地实现等待光标，请使用 CWaitCursor。

示例

// The following example shows how to display the
// hourglass cursor during some lengthy processing
void CMdiView::OnLButtonDown(UINT nFlags, CPoint point)
{
   UNREFERENCED_PARAMETER(nFlags);
   UNREFERENCED_PARAMETER(point);

   AfxGetApp()->DoWaitCursor(1); // 1->>display the hourglass cursor

   // do some lengthy processing
   Sleep(1000);

   AfxGetApp()->DoWaitCursor(-1); // -1->>remove the hourglass cursor
}

// The next example shows DoWaitCursor with parameter 0. It restores
// the hourglass cursor.
void CMdiView::OnMButtonDown(UINT nFlags, CPoint point)
{
   UNREFERENCED_PARAMETER(nFlags);
   UNREFERENCED_PARAMETER(point);

   AfxGetApp()->DoWaitCursor(1); // display the hourglass cursor

   // do some lengthy processing

   // The message box will normally change the cursor to
   // the standard arrow cursor, and leave the cursor in
   // as the standard arrow cursor when the message box is
   // closed.
   AfxMessageBox(_T("DoWaitCursor Sample"));

   // Call DoWaitCursor with parameter 0 to restore
   // the cursor back to the hourglass cursor.
   AfxGetApp()->DoWaitCursor(0);

   // do some more lengthy processing
   Sleep(1000);

   AfxGetApp()->DoWaitCursor(-1); // remove the hourglass cursor
}

CWinApp::EnableD2DSupport

需要 Visual Studio 2010 SP1。

启用应用程序 D2D 支持。 在初始化主窗口之前调用此方法。

BOOL EnableD2DSupport(
    D2D1_FACTORY_TYPE d2dFactoryType = D2D1_FACTORY_TYPE_SINGLE_THREADED,
    DWRITE_FACTORY_TYPE writeFactoryType = DWRITE_FACTORY_TYPE_SHARED);

参数

d2dFactoryType
D2D 工厂的线程模型及其创建的资源。

writeFactoryType
一个指定是将共享还是隔离写入工厂对象的值

返回值

如果启用了 D2D 支持，则返回 TRUE；否则返回 FALSE

CWinApp::EnableHtmlHelp

从 CWinApp 派生的类的构造函数中调用此成员函数，以使用 HTMLHelp 来提供应用程序的帮助。

void EnableHtmlHelp();

注解

CWinApp::EnableShellOpen

调用此函数（通常是从 InitInstance 替代中调用），使应用程序用户在从 Windows 文件管理器中双击文件时可打开数据文件。

void EnableShellOpen();

备注

结合此函数调用 RegisterShellFileTypes 成员函数，或者向应用程序提供一个 .REG 文件用于手动注册文档类型。

示例

// The following code fragment is from CMyApp::InitInstance.
// CMyApp is a CWinApp-derived class.

// enable file manager drag/drop and DDE Execute open
EnableShellOpen();
RegisterShellFileTypes();

CWinApp::EnableTaskbarInteraction

启用任务栏交互。

BOOL EnableTaskbarInteraction(BOOL bEnable = TRUE);

参数

bEnable
指定是应启用 (TRUE) 还是禁用 (FALSE) 与 Windows 7 任务栏的交互。

返回值

如果可启用或禁用任务栏交互，则返回 TRUE。

备注

必须在创建主窗口之前调用此方法，否则它将断言并返回 FALSE。

CWinApp::ExitInstance

由框架从 Run 成员函数内调用以退出此应用程序实例。

virtual int ExitInstance();

返回值

应用程序的退出代码；0 表示无错误，大于 0 的值表示错误。 此值用作来自 WinMain 的返回值。

注解

不要从除了 Run 成员函数内以外的任何位置调用此成员函数。

此函数的默认实现将框架选项写入应用程序的 .INI 文件。 替代此函数，以在应用程序终止时进行清理。

示例

int CMyApp::ExitInstance()
{
   if (m_pMySampleMem)
      delete m_pMySampleMem;

   DoCleanup();

   return CWinApp::ExitInstance();
}

CWinApp::GetApplicationRecoveryParameter

检索应用程序恢复方法的输入参数。

virtual LPVOID GetApplicationRecoveryParameter();

返回值

应用程序恢复方法的默认输入参数。

备注

此函数的默认行为是返回 NULL。

有关详细信息，请参阅 CWinApp::ApplicationRecoveryCallback。

CWinApp::GetApplicationRecoveryPingInterval

返回重启管理器等待恢复回调函数返回的时长。

virtual DWORD GetApplicationRecoveryPingInterval();

返回值

时长（毫秒）。

备注

当向重启管理器注册的应用程序意外退出时，应用程序会尝试保存打开的文档并调用恢复回调函数。 默认恢复回调函数为 CWinApp::ApplicationRecoveryCallback。

框架等待恢复回调函数返回的时长是 ping 间隔。 可通过替代 CWinApp::GetApplicationRecoveryPingInterval 或向 RegisterWithRestartManager 提供自定义值来自定义 ping 间隔。

CWinApp::GetApplicationRestartFlags

返回重启管理器的标志。

virtual DWORD GetApplicationRestartFlags();

返回值

重启管理器的标志。 默认实现将返回 0。

注解

重启管理器的标志对默认实现没有影响。 这些标志供将来使用。

在使用 CWinApp::RegisterWithRestartManager 向重启管理器注册应用程序时设置标志。

重启管理器标志的可能值如下所示：

• RESTART_NO_CRASH

• RESTART_NO_HANG

• RESTART_NO_PATCH

• RESTART_NO_REBOOT

CWinApp::GetAppRegistryKey

返回 HKEY_CURRENT_USER\"Software"\RegistryKey\ProfileName 的项。

HKEY GetAppRegistryKey(CAtlTransactionManager* pTM = NULL);

参数

pTM
指向 CAtlTransactionManager 对象的指针。

返回值

如果函数成功，则返回应用程序键；否则返回 NULL。

备注

CWinApp::GetDataRecoveryHandler

获取应用程序的此实例的数据恢复处理程序。

virtual CDataRecoveryHandler *GetDataRecoveryHandler();

返回值

此应用程序实例的数据恢复处理程序。

备注

使用重启管理器的每个应用程序都必须具有 CDataRecoveryHandler 类的一个实例。 此类负责监视打开的文档并自动保存文件。 CDataRecoveryHandler 的行为取决于重启管理器的配置。 有关详细信息，请参阅 CDataRecoveryHandler 类。

在版本低于 Windows Vista 的操作系统上，此方法返回 NULL。 版本低于 Windows Vista 的操作系统不支持重启管理器。

如果应用程序当前没有数据恢复处理程序，此方法将创建一个并返回指向它的指针。

CWinApp::GetFirstDocTemplatePosition

获取应用程序中第一个文档模板的位置。

POSITION GetFirstDocTemplatePosition() const;

返回值

可用于迭代或对象指针检索的 POSITION 值；如果列表为空，则为 NULL。

注解

使用调用 GetNextDocTemplate 返回的 POSITION 值获取第一个 CDocTemplate 对象。

CWinApp::GetHelpMode

检索应用程序使用的帮助的类型。

AFX_HELP_TYPE GetHelpMode();

返回值

应用程序使用的帮助类型。 有关详细信息，请参阅 CWinApp::m_eHelpType。

CWinApp::GetNextDocTemplate

获取由 pos 标识的文档模板，然后将 pos 设置为 POSITION 值。

CDocTemplate* GetNextDocTemplate(POSITION& pos) const;

参数

pos
对上一次调用 GetNextDocTemplate 或 GetFirstDocTemplatePosition 返回的 POSITION 值的引用。 此值通过此调用更新到下一个位置。

返回值

指向 CDocTemplate 对象的指针。

备注

如果通过调用 GetFirstDocTemplatePosition 建立初始位置，则可以在正向迭代循环中使用 GetNextDocTemplate。

必须确保 POSITION 值有效。 如果该值无效，则 Microsoft 基础类库的调试版本会断言。

如果检索到的文档模板是最后一个可用的文档模板，则 pos 的新值设置为 NULL。

CWinApp::GetPrinterDeviceDefaults

调用此成员函数以准备用于打印的打印机设备上下文。

BOOL GetPrinterDeviceDefaults(struct tagPDA* pPrintDlg);

参数

pPrintDlg
指向 PRINTDLG 结构的指针。

返回值

如果成功，则不为 0；否则为 0。

备注

根据需要从 Windows .INI 文件中检索当前打印机默认设置，或者使用用户在打印安装程序中设置的最后一个打印机配置。

示例

void CMyApp::SetLandscapeMode()
{
   PRINTDLG pd;
   pd.lStructSize = (DWORD)sizeof(PRINTDLG);
   BOOL bRet = GetPrinterDeviceDefaults(&pd);
   if (bRet)
   {
      // protect memory handle with ::GlobalLock and ::GlobalUnlock
      DEVMODE FAR *pDevMode = (DEVMODE FAR*)::GlobalLock(pd.hDevMode);
      // set orientation to landscape
      pDevMode->dmOrientation = DMORIENT_LANDSCAPE;
      ::GlobalUnlock(pd.hDevMode);
   }
}

CWinApp::GetProfileBinary

调用此成员函数，从应用程序的注册表或 .INI 文件的指定部分中的条目检索二进制数据。

BOOL GetProfileBinary(
    LPCTSTR lpszSection,
    LPCTSTR lpszEntry,
    LPBYTE* ppData,
    UINT* pBytes);

参数

lpszSection
指向以 null 结尾的字符串，该字符串指定包含条目的部分。

lpszEntry
指向以 null 结尾的字符串，该字符串包含要检索其值的条目。

ppData
指向将接收数据地址的指针。

pBytes
指向一个 UINT，它将接收数据的大小（以字节为单位）。

返回值

如果成功，则不为 0；否则为 0。

备注

此成员函数不区分大小写，因此 lpszSection 和 lpszEntry 参数中的字符串的大小写可能不同。

注意

GetProfileBinary 会分配缓冲区并在 * ppData 中返回其地址。 调用方负责使用 delete [] 释放缓冲区。

重要

此函数返回的数据不一定是以 NULL 结尾的，并且调用方必须执行验证。 有关详细信息，请参阅 避免缓冲区溢出。

示例

CWinApp* pApp = AfxGetApp();

const TCHAR* pszKey = _T("My Section");
struct complex {
  double re, im;
} myData = { 1.4142, -0.5 };

// Write the information to the registry.

pApp->WriteProfileBinary(pszKey, _T("ComplexData"), (LPBYTE)&myData, 
   sizeof(myData));

// Read the information from the registry.

complex* pData;
UINT n;
BOOL ret = pApp->GetProfileBinary(pszKey, _T("ComplexData"), (LPBYTE*)&pData, 
   &n);

ASSERT(ret);
ASSERT(n == sizeof(complex));
ASSERT(myData.re == pData->re);
ASSERT(myData.im == pData->im);
delete [] pData; // free the buffer

有关其他示例，请参阅 CWinApp::WriteProfileBinary。

CWinApp::GetProfileInt

调用此成员函数以检索应用程序的注册表或 .INI 文件的指定部分中条目的整数的值。

UINT GetProfileInt(
    LPCTSTR lpszSection,
    LPCTSTR lpszEntry,
    int nDefault);

参数

lpszSection
指向以 null 结尾的字符串，该字符串指定包含条目的部分。

lpszEntry
指向以 null 结尾的字符串，该字符串包含要检索其值的条目。

nDefault
指定在框架找不到条目时要返回的默认值。

返回值

如果函数成功，则为指定条目后面的字符串的整数值。 如果函数未找到条目，则返回值为 nDefault 参数的值。 如果与指定条目对应的值不为整数，则返回值为 0。

在 .INI 文件中，此成员函数支持值的十六进制表示法。 检索有符号整数时，应将此值强制转换为 int。

备注

此成员函数不区分大小写，因此 lpszSection 和 lpszEntry 参数中的字符串的大小写可能不同。

重要

此函数返回的数据不一定是以 NULL 结尾的，并且调用方必须执行验证。 有关详细信息，请参阅 避免缓冲区溢出。

示例

CWinApp *pApp = AfxGetApp();

const TCHAR *pszKey = _T("My Section");
const TCHAR *pszName = _T("Julian");
int iAge = 26;

// Write the information to the registry.

pApp->WriteProfileString(pszKey, _T("Name"), pszName);
pApp->WriteProfileInt(pszKey, _T("Age"), iAge);

// Read the information from the registry.

CString strName = pApp->GetProfileString(pszKey, _T("Name"));
int iAge2 = pApp->GetProfileInt(pszKey, _T("Age"), 0);

ASSERT(strName == pszName);
ASSERT(iAge2 == iAge);

有关其他示例，请参阅 CWinApp::WriteProfileInt。

CWinApp::GetProfileString

调用此成员函数，以检索与应用程序的注册表或 .INI 文件的指定部分中条目关联的字符串。

CString GetProfileString(
    LPCTSTR lpszSection,
    LPCTSTR lpszEntry,
    LPCTSTR lpszDefault = NULL);

参数

lpszSection
指向以 null 结尾的字符串，该字符串指定包含条目的部分。

lpszEntry
指向以 null 结尾的字符串，该字符串包含要检索其字符串的条目。 此值不得为 NULL。

lpszDefault
如果无法在初始化文件中找到条目，则指向给定条目的默认字符串值。

返回值

返回值是应用程序的 .INI 文件中的字符串；如果找不到字符串，则为 lpszDefault。 框架支持的最大字符串长度是 _MAX_PATH。 如果 lpszDefault 为 NULL，则返回值为空字符串。

备注

重要

此函数返回的数据不一定是以 NULL 结尾的，并且调用方必须执行验证。 有关详细信息，请参阅 避免缓冲区溢出。

示例

CWinApp *pApp = AfxGetApp();

CString strSection = _T("My Section");
CString strStringItem = _T("My String Item");
CString strIntItem = _T("My Int Item");

pApp->WriteProfileString(strSection, strStringItem, _T("test"));

CString strValue;
strValue = pApp->GetProfileString(strSection, strStringItem);
ASSERT(strValue == _T("test"));

pApp->WriteProfileInt(strSection, strIntItem, 1234);

int nValue;
nValue = pApp->GetProfileInt(strSection, strIntItem, 0);
ASSERT(nValue == 1234);

如需其他示例，请参阅 CWinApp::GetProfileInt 的示例。

CWinApp::GetSectionKey

返回 HKEY_CURRENT_USER\"Software"\RegistryKey\AppName\lpszSection 的项。

HKEY GetSectionKey(
    LPCTSTR lpszSection,
    CAtlTransactionManager* pTM = NULL);

参数

lpszSection
要获取的项的名称。

pTM
指向 CAtlTransactionManager 对象的指针。

返回值

如果函数成功，则返回节键；否则返回 NULL。

备注

CWinApp::HideApplication

调用此成员函数，以便在关闭打开的文档之前隐藏应用程序。

void HideApplication();

CWinApp::HtmlHelp

调用此成员函数可调用 HTMLHelp 应用程序。

virtual void HtmlHelp(
    DWORD_PTR dwData,
    UINT nCmd = 0x000F);

参数

dwData
指定其他数据。 使用的值由 nCmd 参数的值决定。 默认为 0x000F，它表示 HH_HELP_CONTEXT。

nCmd
指定请求的帮助的类型。 若要获取可能值的列表，并了解这些值如何影响 dwData 参数，请参阅 Windows SDK 中的 HtmlHelpW 或 HtmlHelpA API 函数中描述的 uCommand 参数。

备注

框架还会调用此函数来调用 HTMLHelp 应用程序。

当应用程序终止时，框架将自动关闭 HTMLHelp 应用程序。

CWinApp::InitInstance

Windows 允许同时运行同一程序的多个副本。

virtual BOOL InitInstance();

返回值

如果初始化成功，则为非零值；否则为 0。

注解

从概念上来说，应用程序初始化分为两个部分：首次运行程序时执行的一次性应用程序初始化，以及每次运行程序副本时（包括首次运行时）的实例初始化。 框架的 WinMain 实现会调用此函数。

替代 InitInstance 以初始化在 Windows 下运行的应用程序的每个新实例。 通常，替代 InitInstance 来构造主窗口对象，并将 CWinThread::m_pMainWnd 数据成员设置为指向该窗口。 若要详细了解如何替代此成员函数，请参阅 CWinApp：应用程序类。

注意

MFC 应用程序必须初始化为单线程单元 (STA)。 如果在 InitInstance 替代中调用 CoInitializeEx，请指定 COINIT_APARTMENTTHREADED（而不是 COINIT_MULTITHREADED）。

示例

// AppWizard implements the InitInstance overridable function 
// according to options you select.  For example, the multiple document
// interface (MDI) option was chosen for the AppWizard code created
// below. You can add other per-instance initializations to the code
// created by AppWizard.

BOOL CMFCListViewApp::InitInstance()
{
   AfxSetAmbientActCtx(FALSE);
   // Remainder of function definition omitted.

   CWinApp::InitInstance();

   // Initialize OLE libraries
   if (!AfxOleInit())
   {
      AfxMessageBox(_T("OleInit failed."));
      return FALSE;
   }

   // Standard initialization
   // If you are not using these features and wish to reduce the size
   // of your final executable, you should remove from the following
   // the specific initialization routines you do not need
   // Change the registry key under which our settings are stored
   // TODO: You should modify this string to be something appropriate
   // such as the name of your company or organization
   SetRegistryKey(_T("Local AppWizard-Generated Applications"));
   LoadStdProfileSettings(4);  // Load standard INI file options (including MRU)
   // Register the application's document templates.  Document templates
   //  serve as the connection between documents, frame windows and views
   CMultiDocTemplate* pDocTemplate;
   pDocTemplate = new CMultiDocTemplate(IDR_MFCListViewTYPE,
      RUNTIME_CLASS(CMFCListViewDoc),
      RUNTIME_CLASS(CChildFrame), // custom MDI child frame
      RUNTIME_CLASS(CMyListView));
   if (!pDocTemplate)
      return FALSE;
   AddDocTemplate(pDocTemplate);

   // create main MDI Frame window
   CMainFrame* pMainFrame = new CMainFrame;
   if (!pMainFrame || !pMainFrame->LoadFrame(IDR_MAINFRAME))
   {
      delete pMainFrame;
      return FALSE;
   }
   m_pMainWnd = pMainFrame;
   // call DragAcceptFiles only if there's a suffix
   //  In an MDI app, this should occur immediately after setting m_pMainWnd


   // Parse command line for standard shell commands, DDE, file open
   CCommandLineInfo cmdInfo;
   ParseCommandLine(cmdInfo);


   // Dispatch commands specified on the command line.  Will return FALSE if
   // app was launched with /RegServer, /Register, /Unregserver or /Unregister.
   if (!ProcessShellCommand(cmdInfo))
      return FALSE;
   // The main window has been initialized, so show and update it
   pMainFrame->ShowWindow(m_nCmdShow);
   pMainFrame->UpdateWindow();

   return TRUE;
}

CWinApp::IsTaskbarInteractionEnabled

指示是否启用了 Windows 7 任务栏交互。

virtual BOOL IsTaskbarInteractionEnabled();

返回值

如果已调用 EnableTaskbarInteraction，并且操作系统为 Windows 7 或更高版本，则返回 TRUE。

注解

任务栏交互意味着 MDI 应用程序会在单独的选项卡式缩略图中显示 MDI 子级的内容，而当鼠标指针位于应用程序任务栏按钮上方时会显示这些缩略图。

CWinApp::LoadCursor

从当前可执行文件加载由 lpszResourceName 命名或由 nIDResource 指定的光标资源。

HCURSOR LoadCursor(LPCTSTR lpszResourceName) const;  HCURSOR LoadCursor(UINT nIDResource) const;

参数

lpszResourceName
指向包含光标资源名称的以 null 结尾的字符串。 可对此语句使用 CString。

nIDResource
光标对象的 ID。 如需资源列表，请参阅 Windows SDK 中的 LoadCursor。

返回值

如果成功，则为光标的句柄；否则为 NULL。

备注

只有当之前未加载过光标时，LoadCursor 才将光标加载到内存中；否则，它会检索现有资源的句柄。

使用 LoadStandardCursor 或 LoadOEMCursor 成员函数访问预定义的 Windows 光标。

示例

HCURSOR hCursor;

// Load a cursor resource that was originally created using
// the Graphics Editor and assigned the i.d. IDC_MYCURSOR.
hCursor = AfxGetApp()->LoadCursor(IDC_MYCURSOR);

CWinApp::LoadIcon

从可执行文件加载由 lpszResourceName 命名或由 nIDResource 指定的图标资源。

HICON LoadIcon(LPCTSTR lpszResourceName) const;  HICON LoadIcon(UINT nIDResource) const;

参数

lpszResourceName
指向包含图标资源名称的以 null 结尾的字符串。 还可对此语句使用 CString。

nIDResource
图标资源的 ID 编号。

返回值

如果成功，则为图标的句柄；否则为 NULL。

备注

只有当之前未加载过图标时，LoadIcon 才将图标加载到内存中；否则，它会检索现有资源的句柄。

可使用 LoadStandardIcon 或 LoadOEMIcon 成员函数访问预定义的 Windows 图标。

注意

此成员函数调用 Win32 API 函数 LoadIcon，后者只能加载大小符合 SM_CXICON 和 SM_CYICON 系统指标值的图标。

CWinApp::LoadOEMCursor

加载 nIDCursor 指定的 Windows 预定义光标资源。

HCURSOR LoadOEMCursor(UINT nIDCursor) const;

参数

nIDCursor
指定预定义 Windows 光标的 OCR_ 清单常量标识符。 必须在 #include \<afxwin.h> 前面具有 #define OEMRESOURCE 才有权访问 WINDOWS.H 中的 OCR_ 常量。

返回值

如果成功，则为光标的句柄；否则为 NULL。

备注

使用 LoadOEMCursor 或 LoadStandardCursor 成员函数访问预定义的 Windows 光标。

示例

// In the stdafx.h file, add #define OEMRESOURCE to
// include the windows.h definitions of OCR_ values.
#define OEMRESOURCE
#include <afxwin.h> // MFC core and standard components
#include <afxext.h> // MFC extensions

 

HCURSOR hCursor;
// Load the predefined WIndows "size all" cursor.
hCursor = AfxGetApp()->LoadOEMCursor(OCR_SIZEALL);

CWinApp::LoadOEMIcon

加载 nIDIcon 指定的 Windows 预定义图标资源。

HICON LoadOEMIcon(UINT nIDIcon) const;

参数

nIDIcon
指定预定义 Windows 图标的 OIC_ 清单常量标识符。 必须在 #include \<afxwin.h> 前面具有 #define OEMRESOURCE 才有权访问 WINDOWS.H 中的 OIC_ 常量。

返回值

如果成功，则为图标的句柄；否则为 NULL。

备注

使用 LoadOEMIcon 或 LoadStandardIcon 成员函数访问预定义的 Windows 图标。

CWinApp::LoadStandardCursor

加载由 lpszCursorName 指定的 Windows 预定义光标资源。

HCURSOR LoadStandardCursor(LPCTSTR lpszCursorName) const;

参数

lpszCursorName
指定预定义 Windows 光标的 IDC_ 清单常量标识符。 这些标识符在 WINDOWS.H 中定义。 以下列表显示了 lpszCursorName 的可能预定义值和含义：

• IDC_ARROW 标准箭头光标

• IDC_IBEAM 标准文本插入光标

• Windows 执行耗时的任务时使用的 IDC_WAIT 沙漏光标

• 用于选择的 IDC_CROSS 十字光标

• 垂直向上的 IDC_UPARROW 箭头

• IDC_SIZE 已过时且不受支持；请使用 IDC_SIZEALL

• IDC_SIZEALL 四向箭头。 用于调整窗口大小的光标。

• IDC_ICON 已过时且不受支持。 使用 IDC_ARROW。

• IDC_SIZENWSE 双头箭头，箭头在左上侧和右下侧

• IDC_SIZENWSE 双头箭头，箭头在右上侧和左下侧

• IDC_SIZEWE 水平双向箭头

• IDC_SIZEWE 垂直双向箭头

返回值

如果成功，则为光标的句柄；否则为 NULL。

注解

使用 LoadStandardCursor 或 LoadOEMCursor 成员函数访问预定义的 Windows 光标。

示例

HCURSOR hCursor;

// Load the predefined Windows "up arrow" cursor.
hCursor = AfxGetApp()->LoadStandardCursor(IDC_UPARROW);

CWinApp::LoadStandardIcon

加载由 lpszIconName 指定的 Windows 预定义图标资源。

HICON LoadStandardIcon(LPCTSTR lpszIconName) const;

参数

lpszIconName
指定预定义 Windows 图标的清单常量标识符。 这些标识符在 WINDOWS.H 中定义。 如需可能的预定义值及其说明的列表，请查看 Windows SDK 中的 LoadIcon 中的 lpIconName 参数。

返回值

如果成功，则为图标的句柄；否则为 NULL。

备注

使用 LoadStandardIcon 或 LoadOEMIcon 成员函数访问预定义的 Windows 图标。

CWinApp::LoadStdProfileSettings

从 InitInstance 成员函数内部调用此成员函数，以启用并加载最近使用的 (MRU) 文件和上次预览状态的列表。

void LoadStdProfileSettings(UINT nMaxMRU = _AFX_MRU_COUNT);

参数

nMaxMRU
要跟踪的最近使用的文件数。

备注

如果 nMaxMRU 为 0，则不会维护 MRU 列表。

CWinApp::m_bHelpMode

如果应用程序处于帮助上下文模式中（通常使用 Shift + F1 调用），则为 TRUE；否则为 FALSE。

BOOL m_bHelpMode;

注解

在帮助上下文模式下，光标变为问号，并且用户可在屏幕上移动它。 如果要在帮助模式下实现特定处理，请检查此标志。 m_bHelpMode 是 BOOL 类型的公共变量。

CWinApp::m_dwRestartManagerSupportFlags

用于确定重启管理器行为的标志。

DWORD m_dwRestartManagerSupportFlags;

备注

若要启用重启管理器，请将 m_dwRestartManagerSupportFlags 设置为所需的行为。 下表显示了可用的标志。

标记	说明
AFX_RESTART_MANAGER_SUPPORT_RESTART	应用程序是使用 CWinApp::RegisterWithRestartManager 注册的。 如果应用程序意外退出，重启管理器负责重启该应用程序。
- AFX_RESTART_MANAGER_SUPPORT_RECOVERY	应用程序注册到重启管理器，重启管理器在重启应用程序时调用恢复回调函数。 默认恢复回调函数为 CWinApp::ApplicationRecoveryCallback。
- AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART	已启用自动保存功能，重启管理器在应用程序重启时自动保存任何打开的文档。
- AFX_RESTART_MANAGER_AUTOSAVE_AT_INTERVAL	已启用自动保存功能，重启管理器按定期间隔自动保存任何打开的文档。 时间间隔由 CWinApp::m_nAutosaveInterval 定义。
- AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES	重启管理器在重启意外退出的应用程序后打开之前打开的文档。 CDataRecoveryHandler 类负责存储打开的文档列表并还原它们。
- AFX_RESTART_MANAGER_RESTORE_AUTOSAVED_FILES	重启管理器提示用户在重启应用程序后还原自动保存的文件。 CDataRecoveryHandler 类查询用户。
- AFX_RESTART_MANAGER_SUPPORT_NO_AUTOSAVE	AFX_RESTART_MANAGER_SUPPORT_RESTART、AFX_RESTART_MANAGER_SUPPORT_RECOVER 和 AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES 的并集。
- AFX_RESTART_MANAGER_SUPPORT_ALL_ASPECTS	AFX_RESTART_MANAGER_SUPPORT_NO_AUTOSAVE、AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART、AFX_RESTART_MANAGER_AUTOSAVE_AT_INTERVAL 和 AFX_RESTART_MANAGER_RESTORE_AUTOSAVED_FILES 的并集。
- AFX_RESTART_MANAGER_SUPPORT_RESTART_ASPECTS	AFX_RESTART_MANAGER_SUPPORT_RESTART、AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART、AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES 和 AFX_RESTART_MANAGER_RESTORE_AUTOSAVED_FILES 的并集。
- AFX_RESTART_MANAGER_SUPPORT_RECOVERY_ASPECTS	AFX_RESTART_MANAGER_SUPPORT_RECOVERY、AFX_RESTART_MANAGER_AUTOSAVE_AT_INTERVAL、AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES 和 AFX_RESTART_MANAGER_RESTORE_AUTOSAVED_FILES 的并集。

CWinApp::m_eHelpType

此数据成员的类型是 CWinApp 类中定义的枚举类型 AFX_HELP_TYPE。

AFX_HELP_TYPE m_eHelpType;

备注

AFX_HELP_TYPE 枚举的定义如下所示：

enum AFX_HELP_TYPE {
    afxWinHelp = 0,
    afxHTMLHelp = 1
    };

• 若要将应用程序的帮助设置为 HTML 帮助，请调用 SetHelpMode 并指定 afxHTMLHelp。

• 若要将应用程序的帮助设置为 HTML 帮助，请调用 SetHelpMode 并指定 afxWinHelp。

CWinApp::m_hInstance

对应于 Windows 传递给 WinMain 的 hInstance 参数。

HINSTANCE m_hInstance;

备注

m_hInstance 数据成员是在 Windows 下运行的应用程序的当前实例的句柄。 这是由全局函数 AfxGetInstanceHandle 返回的。 m_hInstance 是 HINSTANCE 类型的公共变量。

示例

// Typically you do not need to pass the application's hInstance
// to Windows APIs directly because there are equivalent MFC
// member functions that pass the hInstance for you.  The following
// example is not typical:

HCURSOR hCursor;
hCursor = ::LoadCursor(AfxGetApp()->m_hInstance, 
   MAKEINTRESOURCE(IDC_MYCURSOR));

// A more direct way to get the application's hInstance is to
// call AfxGetInstanceHandle:
hCursor = ::LoadCursor(AfxGetInstanceHandle(), 
   MAKEINTRESOURCE(IDC_MYCURSOR));

// If you need the hInstance to load a resource, it is better
// to call AfxGetResourceHandle instead of AfxGetInstanceHandle:
hCursor = ::LoadCursor(AfxGetResourceHandle(), 
   MAKEINTRESOURCE(IDC_MYCURSOR));

// A better way to load the cursor resource is to call
// CWinApp::LoadCursor
hCursor = AfxGetApp()->LoadCursor(IDC_MYCURSOR);

CWinApp::m_lpCmdLine

对应于 Windows 传递给 WinMain 的 lpCmdLine 参数。

LPTSTR m_lpCmdLine;

备注

指向指定应用程序的命令行的以 null 结尾的字符串。 使用 m_lpCmdLine 来访问用户在启动应用程序时输入的任何命令行参数。 m_lpCmdLine 是 LPTSTR 类型的公共变量。

示例

if (m_lpCmdLine[0] == _T('\0'))
{
   // Create a new (empty) document.
   OnFileNew();
}
else
{
   // Open a file passed as the first command line parameter.
   OpenDocumentFile(m_lpCmdLine);
}

CWinApp::m_nAutosaveInterval

自动保存的间隔时长（毫秒）。

int m_nAutosaveInterval;

备注

可以将重启管理器配置为按设定间隔自动保存打开的文档。 如果应用程序没有自动保存文件，则此参数不起作用。

CWinApp::m_nCmdShow

对应于 Windows 传递给 WinMain 的 nCmdShow 参数。

int m_nCmdShow;

备注

为应用程序的主窗口调用 CWnd::ShowWindow 时，应将 m_nCmdShow 作为参数传递。 m_nCmdShow 是 int 类型的公共变量。

示例

// The following code fragment is taken from CMyApp::InitInstance.
// CMyApp is derived from CWinApp.

// The main window has been initialized, so show and update it
// using the nCmdShow parameter passed to the application when it
// was first launched.
// pMainFrame is the main MDI frame window of our app and is derived
// from CMDIFrameWnd.
pMainFrame->ShowWindow(m_nCmdShow);
pMainFrame->UpdateWindow();

CWinApp::m_pActiveWnd

使用此数据成员来存储指向已就地激活 OLE 服务器应用程序的 OLE 容器应用程序的主窗口的指针。

备注

如果此数据成员为 NULL，则应用程序不是就地激活的。

框架在 OLE 容器应用程序就地激活框架窗口时设置此成员变量。

CWinApp::m_pDataRecoveryHandler

指向应用程序的数据恢复处理程序的指针。

CDataRecoveryHandler* m_pDataRecoveryHandler;

备注

应用程序的数据恢复处理程序会监视打开的文档并自动保存它们。 当应用程序在意外退出后重启时，框架使用数据恢复处理程序来还原自动保存的文件。 有关详细信息，请参阅 CDataRecoveryHandler 类。

CWinApp::m_pszAppName

指定应用程序的名称。

LPCTSTR m_pszAppName;

备注

应用程序名称可以来自传递给 CWinApp 构造函数的参数；如果未指定，则来自传递给 ID 为 AFX_IDS_APP_TITLE 的资源字符串的参数。 如果在资源中找不到应用程序名称，则它来自程序的 .EXE 文件名。

由全局函数 AfxGetAppName 返回。 m_pszAppName 是 const char* 类型的公共变量。

注意

如果将值赋给 m_pszAppName，则必须在堆上动态分配该值。 CWinApp 析构函数使用此指针调用 free( )。 你可能需要使用 _tcsdup( ) 运行时库函数来执行分配。 此外，在分配新值之前释放与当前指针关联的内存。 例如：

//First free the string allocated by MFC at CWinApp startup.
//The string is allocated before InitInstance is called.
free((void*)m_pszAppName);
//Change the name of the application file.
//The CWinApp destructor will free the memory.
m_pszAppName = _tcsdup(_T("c:\\somedir\\myapp.exe"));

示例

CWnd *pWnd = AfxGetMainWnd();
// Set pWnd to some CWnd object whose window has already
// been created.

// The following call to CWnd::MessageBox uses the application
// title as the message box caption.
pWnd->MessageBox(_T("Some message"), AfxGetApp()->m_pszAppName);

// A more direct way to get the application title is to
// call AfxGetAppName:
pWnd->MessageBox(_T("Some message"), AfxGetAppName());

// An easier way to display a message box using the application
// title as the message box caption is to call AfxMessageBox:
AfxMessageBox(_T("Some message"));

CWinApp::m_pszExeName

包含没有扩展名的应用程序可执行文件的名称。

LPCTSTR m_pszExeName;

备注

与 m_pszAppName 不同，此名称不能包含空白。 m_pszExeName 是 const char* 类型的公共变量。

注意

如果将值赋给 m_pszExeName，则必须在堆上动态分配该值。 CWinApp 析构函数使用此指针调用 free( )。 你可能需要使用 _tcsdup( ) 运行时库函数来执行分配。 此外，在分配新值之前释放与当前指针关联的内存。 例如：

//First free the string allocated by MFC at CWinApp startup.
//The string is allocated before InitInstance is called.
free((void*)m_pszExeName);
//Change the name of the .EXE file.
//The CWinApp destructor will free the memory.
m_pszExeName = _tcsdup(_T("c:\\somedir\\myapp"));

CWinApp::m_pszHelpFilePath

包含应用程序帮助文件的路径。

LPCTSTR m_pszHelpFilePath;

注解

默认情况下，框架将 m_pszHelpFilePath 初始化为带“.HLP”后缀的应用程序名称。 若要更改帮助文件的名称，请设置 m_pszHelpFilePath，使其指向包含所需帮助文件的完整名称的字符串。 可在应用程序的 InitInstance 函数中便捷地执行此操作。 m_pszHelpFilePath 是 const char* 类型的公共变量。

注意

如果将值赋给 m_pszHelpFilePath，则必须在堆上动态分配该值。 CWinApp 析构函数使用此指针调用 free( )。 你可能需要使用 _tcsdup( ) 运行时库函数来执行分配。 此外，在分配新值之前释放与当前指针关联的内存。 例如：

//First free the string allocated by MFC at CWinApp startup.
//The string is allocated before InitInstance is called.
free((void*)m_pszHelpFilePath);
//Change the name of the .HLP file.
//The CWinApp destructor will free the memory.
m_pszHelpFilePath = _tcsdup(_T("c:\\somedir\\myhelp.hlp"));

CWinApp::m_pszProfileName

包含应用程序的 .INI 文件的名称。

LPCTSTR m_pszProfileName;

备注

m_pszProfileName 是 const char* 类型的公共变量。

注意

如果将值赋给 m_pszProfileName，则必须在堆上动态分配该值。 CWinApp 析构函数使用此指针调用 free( )。 你可能需要使用 _tcsdup( ) 运行时库函数来执行分配。 此外，在分配新值之前释放与当前指针关联的内存。 例如：

//First free the string allocated by MFC at CWinApp startup.
//The string is allocated before InitInstance is called.
free((void*)m_pszProfileName);
//Change the name of the .INI file.
//The CWinApp destructor will free the memory.
m_pszProfileName = _tcsdup(_T("c:\\somedir\\myini.ini"));

CWinApp::m_pszRegistryKey

用于确定应用程序配置文件设置在注册表或 INI 文件中存储位置。

LPCTSTR m_pszRegistryKey;

备注

通常，此数据成员被视为只读成员。

• 该值存储在注册表项中。 应用程序配置文件设置的名称追加到以下注册表项：HKEY_CURRENT_USER/Software/LocalAppWizard-Generated/。

如果将值赋给 m_pszRegistryKey，则必须在堆上动态分配该值。 CWinApp 析构函数使用此指针调用 free( )。 你可能需要使用 _tcsdup( ) 运行时库函数来执行分配。 此外，在分配新值之前释放与当前指针关联的内存。 例如：

//First free the string allocated by MFC at CWinApp startup.
//The string is allocated before InitInstance is called.
free((void*)m_pszRegistryKey);
//Change the name of the registry key.
//The CWinApp destructor will free the memory.
m_pszRegistryKey = _tcsdup(
    _T("HKEY_CURRENT_USER\\Software\\mycompany\\myapp\\thissection\\thisvalue"));

CWinApp::m_pszAppID

应用程序用户模型 ID。

LPCTSTR m_pszAppID;

备注

CWinApp::OnContextHelp

处理应用程序中的 Shift+F1 帮助。

afx_msg void OnContextHelp();

备注

必须向 CWinApp 类消息映射添加 ON_COMMAND( ID_CONTEXT_HELP, OnContextHelp ) 语句，并添加快捷键表条目（通常为 Shift+F1）来启用此成员函数。

OnContextHelp 将应用程序置于帮助模式。 光标会更改为箭头和问号，随后用户可移动鼠标指针，再按鼠标左键来选择对话框、窗口、菜单或命令按钮。 此成员函数会检索光标下对象的帮助上下文，并使用该帮助上下文调用 Windows 函数 WinHelp。

CWinApp::OnDDECommand

当主框架窗口收到 DDE 执行消息时由框架调用。

virtual BOOL OnDDECommand(LPTSTR lpszCommand);

参数

lpszCommand
指向应用程序收到的 DDE 命令字符串。

返回值

如果已处理命令，则为非零值；否则为 0。

备注

默认实现检查命令是否是打开文档的请求；如果是，则打开指定的文档。 当用户双击数据文件时，Windows 文件管理器通常会发送此类 DDE 命令字符串。 替代此函数以处理其他 DDE execute 命令，例如要打印的命令。

示例

BOOL CMyApp::OnDDECommand(LPTSTR lpszCommand)
{
   if (CWinApp::OnDDECommand(lpszCommand))
      return TRUE;

   // Handle any DDE commands recognized by your application
   // and return TRUE.  See implementation of CWinApp::OnDDEComand
   // for example of parsing the DDE command string.

   // Return FALSE for any DDE commands you do not handle.
   return FALSE;
}

CWinApp::OnFileNew

实现 ID_FILE_NEW 命令。

afx_msg void OnFileNew();

注解

必须将 ON_COMMAND( ID_FILE_NEW, OnFileNew ) 语句添加到 CWinApp 类消息映射，才能启用此成员函数。 如果启用，此函数将处理 File New 命令的执行。

若要了解默认行为并查看如何替代此成员函数，请参阅技术说明 22。

示例

// The following message map, produced by the Application Wizard, binds
// the File New, Open, and Print Setup menu commands to default
// framework implementations of these commands.
BEGIN_MESSAGE_MAP(CStdApp, CWinApp)
// Standard file based document commands
ON_COMMAND(ID_FILE_NEW, &CWinApp::OnFileNew)
ON_COMMAND(ID_FILE_OPEN, &CWinApp::OnFileOpen)
// Standard print setup command
ON_COMMAND(ID_FILE_PRINT_SETUP, &CWinApp::OnFilePrintSetup)
END_MESSAGE_MAP()

 

// The following message map illustrates how to rebind the
// File New, Open and Print Setup menu commands to handlers that
// you implement in your CWinApp-derived class.
// Note, you can name the handler CCustomApp::OnFileNew instead of
// CCustomApp::OnMyFileNew, and likewise for the other handlers, if desired.
BEGIN_MESSAGE_MAP(CCustomApp, CWinApp)
ON_COMMAND(ID_FILE_NEW, &CCustomApp::OnMyFileNew)
ON_COMMAND(ID_FILE_OPEN, &CCustomApp::OnMyFileOpen)
ON_COMMAND(ID_FILE_PRINT_SETUP, &CCustomApp::OnMyFilePrintSetup)
END_MESSAGE_MAP()

CWinApp::OnFileOpen

实现 ID_FILE_OPEN 命令。

afx_msg void OnFileOpen();

备注

必须将 ON_COMMAND( ID_FILE_OPEN, OnFileOpen ) 语句添加到 CWinApp 类消息映射，才能启用此成员函数。 如果启用，此函数将处理 File Open 命令的执行。

若要了解默认行为并查看如何替代此成员函数，请参阅技术说明 22。

示例

// The following message map, produced by the Application Wizard, binds
// the File New, Open, and Print Setup menu commands to default
// framework implementations of these commands.
BEGIN_MESSAGE_MAP(CStdApp, CWinApp)
// Standard file based document commands
ON_COMMAND(ID_FILE_NEW, &CWinApp::OnFileNew)
ON_COMMAND(ID_FILE_OPEN, &CWinApp::OnFileOpen)
// Standard print setup command
ON_COMMAND(ID_FILE_PRINT_SETUP, &CWinApp::OnFilePrintSetup)
END_MESSAGE_MAP()

 

// The following message map illustrates how to rebind the
// File New, Open and Print Setup menu commands to handlers that
// you implement in your CWinApp-derived class.
// Note, you can name the handler CCustomApp::OnFileNew instead of
// CCustomApp::OnMyFileNew, and likewise for the other handlers, if desired.
BEGIN_MESSAGE_MAP(CCustomApp, CWinApp)
ON_COMMAND(ID_FILE_NEW, &CCustomApp::OnMyFileNew)
ON_COMMAND(ID_FILE_OPEN, &CCustomApp::OnMyFileOpen)
ON_COMMAND(ID_FILE_PRINT_SETUP, &CCustomApp::OnMyFilePrintSetup)
END_MESSAGE_MAP()

CWinApp::OnFilePrintSetup

实现 ID_FILE_PRINT_SETUP 命令。

afx_msg void OnFilePrintSetup();

注解

必须将 ON_COMMAND( ID_FILE_PRINT_SETUP, OnFilePrintSetup ) 语句添加到 CWinApp 类消息映射，才能启用此成员函数。 如果启用，此函数将处理 File Print 命令的执行。

若要了解默认行为并查看如何替代此成员函数，请参阅技术说明 22。

示例

// The following message map, produced by the Application Wizard, binds
// the File New, Open, and Print Setup menu commands to default
// framework implementations of these commands.
BEGIN_MESSAGE_MAP(CStdApp, CWinApp)
// Standard file based document commands
ON_COMMAND(ID_FILE_NEW, &CWinApp::OnFileNew)
ON_COMMAND(ID_FILE_OPEN, &CWinApp::OnFileOpen)
// Standard print setup command
ON_COMMAND(ID_FILE_PRINT_SETUP, &CWinApp::OnFilePrintSetup)
END_MESSAGE_MAP()

 

// The following message map illustrates how to rebind the
// File New, Open and Print Setup menu commands to handlers that
// you implement in your CWinApp-derived class.
// Note, you can name the handler CCustomApp::OnFileNew instead of
// CCustomApp::OnMyFileNew, and likewise for the other handlers, if desired.
BEGIN_MESSAGE_MAP(CCustomApp, CWinApp)
ON_COMMAND(ID_FILE_NEW, &CCustomApp::OnMyFileNew)
ON_COMMAND(ID_FILE_OPEN, &CCustomApp::OnMyFileOpen)
ON_COMMAND(ID_FILE_PRINT_SETUP, &CCustomApp::OnMyFilePrintSetup)
END_MESSAGE_MAP()

CWinApp::OnHelp

处理应用程序中的 F1 帮助（使用当前上下文）。

afx_msg void OnHelp();

注解

通常，还会为 F1 键添加快捷键条目。 启用 F1 键只是一项约定，不是强制要求。

必须将 ON_COMMAND( ID_HELP, OnHelp ) 语句添加到 CWinApp 类消息映射，才能启用此成员函数。 如果启用，则在用户按 F1 键时由框架调用。

此消息处理程序函数的默认实现会确定对应于当前窗口、对话框或菜单项的帮助上下文，然后调用 WINHELP.EXE。 如果当前没有上下文可用，该函数将使用默认上下文。

替代此成员函数，将帮助上下文设置为当前具有焦点的窗口、对话框、菜单项或工具栏按钮以外的其他内容。 使用所需的帮助上下文 ID 调用 WinHelp。

CWinApp::OnHelpFinder

处理 ID_HELP_FINDER 和 ID_DEFAULT_HELP 命令。

afx_msg void OnHelpFinder();

备注

必须将 ON_COMMAND( ID_HELP_FINDER, OnHelpFinder ) 语句添加到 CWinApp 类消息映射，才能启用此成员函数。 如果启用，则在应用程序用户选择 Help Finder 命令来使用标准 HELP_FINDER 主题调用 WinHelp 时，框架会调用此消息处理程序函数。

CWinApp::OnHelpIndex

处理 ID_HELP_INDEX 命令，并提供默认帮助主题。

afx_msg void OnHelpIndex();

备注

必须将 ON_COMMAND( ID_HELP_INDEX, OnHelpIndex ) 语句添加到 CWinApp 类消息映射，才能启用此成员函数。 如果启用，则在应用程序用户选择 Help Index 命令来使用标准 HELP_INDEX 主题调用 WinHelp 时，框架会调用此消息处理程序函数。

CWinApp::OnHelpUsing

处理 ID_HELP_USING 命令。

afx_msg void OnHelpUsing();

备注

必须将 ON_COMMAND( ID_HELP_USING, OnHelpUsing ) 语句添加到 CWinApp 类消息映射，才能启用此成员函数。 在应用程序用户选择 Help Using 命令来使用标准 HELP_HELPONHELP 主题调用 WinHelp 应用程序时，框架会调用此消息处理程序函数。

CWinApp::OnIdle

替代此成员函数以执行空闲时间处理。

virtual BOOL OnIdle(LONG lCount);

参数

lCount
每当应用程序的消息队列为空而调用 OnIdle 时递增的计数器。 每次处理新消息时，此计数将重置为 0。 可使用 lCount 参数来确定应用程序在没有处理消息的情况下的相对空闲时长。

返回值

若要接收更多空闲处理时间，则为非零值；如果不再需要更多空闲时间，则为 0。

备注

当应用程序的消息队列为空时，会在默认消息循环中调用 OnIdle。 使用替代以调用自己的后台空闲处理程序任务。

OnIdle 应返回 0 以指示不需要空闲处理时间。 每当消息队列为空而调用 时，lCount 参数都会递增，并且在每次处理新消息时重置为 0。OnIdle 可以基于此计数调用不同的空闲例程。

下面总结了空闲循环处理：

1. 如果 Microsoft 基础类库中的消息循环检查消息队列，且没有找到挂起的消息，则为应用程序对象调用 OnIdle 并提供 0 作为 lCount 参数。

2. OnIdle 会执行一些处理并返回非零值，以指示应再次调用它来执行进一步处理。

3. 消息循环会再次检查消息队列。 如果没有消息挂起，它将再次调用 OnIdle，从而递增 lCount 参数。

4. 最终，OnIdle 完成其所有空闲任务的处理并返回 0。 这指示消息循环停止调用 OnIdle，直到从消息队列接收到下一条消息，此时空闲周期会重启，参数设置为 0。

不要在 OnIdle 期间执行冗长的任务，因为应用程序在 OnIdle 返回之前无法处理用户输入。

注意

OnIdle 的默认实现会更新命令用户界面对象（例如菜单项和工具栏按钮），并执行内部数据结构清理。 因此，如果替代 OnIdle，则必须使用替代版本中的 lCount 调用 CWinApp::OnIdle。 首先调用所有基类空闲处理（即，直到基类 OnIdle 返回 0）。 如果需要在基类处理完成之前执行工作，请查看基类实现，选择要在其中执行工作的适当 lCount。

如果不希望每次从消息队列中检索到消息时都调用 OnIdle，可替代 CWinThreadIsIdleMessage。 如果应用程序设置的计时器很短，或者系统正在发送 WM_SYSTIMER 消息，则将反复调用 OnIdle，这会降低性能。

示例

下面两个示例演示如何使用 OnIdle。 第一个示例使用 lCount 参数处理两个空闲任务，从而确定任务的优先级。 第一个任务的优先级高，应该尽可能地执行它。 第二个任务不那么重要，应该仅在用户输入长时间停顿时才执行。 请注意对 OnIdle 基类版本的调用。 第二个示例管理一组具有不同优先级的空闲任务。

BOOL CMyApp::OnIdle(LONG lCount)
{
   BOOL bMore = CWinApp::OnIdle(lCount);

   if (lCount == 0)
   {
      TRACE(_T("App idle for short period of time\n"));
      bMore = TRUE;
   }
   else if (lCount == 10)
   {
      TRACE(_T("App idle for longer amount of time\n"));
      bMore = TRUE;
   }
   else if (lCount == 100)
   {
      TRACE(_T("App idle for even longer amount of time\n"));
      bMore = TRUE;
   }
   else if (lCount == 1000)
   {
      TRACE(_T("App idle for quite a long period of time\n"));
      // bMore is not set to TRUE, no longer need idle
      // IMPORTANT: bMore is not set to FALSE since CWinApp::OnIdle may
      // have more idle tasks to complete.
   }

   return bMore;
   // return TRUE as long as there are any more idle tasks
}

CWinApp::OpenDocumentFile

框架调用此方法来打开应用程序的命名 CDocument 文件。

virtual CDocument* OpenDocumentFile(
    LPCTSTR lpszFileName
    BOOL bAddToMRU = TRUE);

参数

lpszFileName
[in] 要打开之文件的名称。

bAddToMRU
[in] TRUE 表示该文档是最新的文件之一；FALSE 表示该文档不是最新文件之一。

返回值

如果成功，则为指向 CDocument 的指针；否则为 NULL。

注解

如果具有该名称的文档已打开，则包含该文档的第一个框架窗口将获得焦点。 如果应用程序支持多个文档模板，则框架使用文件扩展名查找相应的文档模板来尝试加载文档。 如果成功，则文档模板将为文档创建框架窗口和视图。

示例

if (m_lpCmdLine[0] == _T('\0'))
{
   // Create a new (empty) document.
   OnFileNew();
}
else
{
   // Open a file passed as the first command line parameter.
   OpenDocumentFile(m_lpCmdLine);
}

CWinApp::ParseCommandLine

调用此成员函数来分析命令行并将参数逐一发送到 CCommandLineInfo::ParseParam。

void ParseCommandLine(CCommandLineInfo& rCmdInfo);

参数

rCmdInfo
对 CCommandLineInfo 对象的引用。

注解

使用应用程序向导启动新的 MFC 项目时，应用程序向导将创建 CCommandLineInfo 的本地实例，然后在 InitInstance 成员函数中调用 ProcessShellCommand 和 ParseCommandLine。 命令行遵循下述路由：

1. 在 InitInstance 中创建后，对象 CCommandLineInfo 将传递给 ParseCommandLine。

2. ParseCommandLine 随后会重复调用 CCommandLineInfo::ParseParam，针对每个参数调用一次。

3. ParseParam 填充 CCommandLineInfo 对象，该对象随后传递给 ProcessShellCommand。

4. ProcessShellCommand 处理命令行参数和标志。

请注意，可根据需要直接调用 ParseCommandLine。

有关命令行标志的说明，请参阅 CCommandLineInfo::m_nShellCommand。

CWinApp::PreTranslateMessage

替代此函数来筛选窗口消息，然后再将其分配至 Windows 函数 TranslateMessage 和 DispatchMessage。默认实现会执行快捷键转换，因此必须在替代版本中调用 CWinApp::PreTranslateMessage 成员函数。

virtual BOOL PreTranslateMessage(MSG* pMsg);

参数

pMsg
指向包含要处理的消息的 MSG 结构的指针。

返回值

如果消息已在 PreTranslateMessage 中完全处理且不应进一步处理，则为非零值。 如果消息应以正常方式处理，则为零。

CWinApp::ProcessMessageFilter

框架的挂钩函数调用此成员函数来筛选和响应某些 Windows 消息。

virtual BOOL ProcessMessageFilter(
    int code,
    LPMSG lpMsg);

参数

code
指定挂钩代码。 此成员函数使用此代码来确定如何处理 lpMsg。

lpMsg
指向 Windows MSG 结构的指针。

返回值

如果消息已处理，则为非零值；否则为 0。

注解

挂钩函数将在事件发送到应用程序的正常消息处理之前处理事件。

如果替代此高级功能，请确保调用基类版本以维护框架的挂钩处理。

CWinApp::ProcessShellCommand

InitInstance 调用此成员函数以接受从 CCommandLineInfo 对象传递的参数（该对象由 rCmdInfo 识别），并执行指示的操作。

BOOL ProcessShellCommand(CCommandLineInfo& rCmdInfo);

参数

rCmdInfo
对 CCommandLineInfo 对象的引用。

返回值

如果成功处理 shell 命令，则为非零值。 如果为 0，则从 InitInstance 返回 FALSE。

备注

使用应用程序向导启动新的 MFC 项目时，应用程序向导将创建 CCommandLineInfo 的本地实例，然后在 InitInstance 成员函数中调用 ProcessShellCommand 和 ParseCommandLine。 命令行遵循下述路由：

1. 在 InitInstance 中创建后，对象 CCommandLineInfo 将传递给 ParseCommandLine。

2. ParseCommandLine 随后会重复调用 CCommandLineInfo::ParseParam，针对每个参数调用一次。

3. ParseParam 填充 CCommandLineInfo 对象，该对象随后传递给 ProcessShellCommand。

4. ProcessShellCommand 处理命令行参数和标志。

由 CCommandLineInfo::m_nShellCommand 标识的 CCommandLineInfo 对象的数据成员属于以下枚举类型，在 CCommandLineInfo 类中进行定义。

enum {
    FileNew,
    FileOpen,
    FilePrint,
    FilePrintTo,
    FileDDE
    };

有关上述每个值的简要说明，请参阅 CCommandLineInfo::m_nShellCommand。

CWinApp::ProcessWndProcException

每当处理程序未捕获在应用程序的某个消息或命令处理程序中引发的异常时，框架都会调用此成员函数。

virtual LRESULT ProcessWndProcException(
    CException* e,
    const MSG* pMsg);

参数

e
指向未捕获的异常的指针。

pMsg
一个 MSG 结构，其中包含有关导致框架引发异常的 Windows 消息的信息。

返回值

应返回到 Windows 的值。 对于 Windows 消息，这通常为 0L；对于命令消息，则为 1L (TRUE)。

注解

请勿直接调用此成员函数。

此成员函数的默认实现将创建一个消息框。 如果未捕获的异常源自菜单、工具栏或快捷键命令失败，则消息框显示“命令失败”消息；否则，会显示“内部应用程序错误”消息。

替代此成员函数以提供异常的全局处理。 仅在希望显示消息框时调用基本功能。

CWinApp::Register

执行 RegisterShellFileTypes 未处理的任何注册任务。

virtual BOOL Register();

返回值

若成功，则为非零；否则为 0。

备注

默认实现只返回 TRUE。 替代此函数以提供任何自定义注册步骤。

CWinApp::RegisterShellFileTypes

调用此成员函数，向 Windows 文件管理器注册应用程序的所有文档类型。

void RegisterShellFileTypes(BOOL bCompat = FALSE);

参数

bCompat
[in] 如果为 TRUE，则为 shell 命令 Print 和 Print To 添加注册条目，从而使用户能够直接从 shell 打印文件，或者通过将文件拖动到打印机对象进行打印。 它还会添加一个 DefaultIcon 键。 默认情况下，此参数为 FALSE，以实现向后兼容性。

备注

这样，用户可在文件管理器内双击应用程序创建的数据文件来打开此文件。 在为应用程序中的每个文档模板调用 AddDocTemplate 后调用 RegisterShellFileTypes。 调用 RegisterShellFileTypes 时还调用 EnableShellOpen 成员函数。

RegisterShellFileTypes 会循环访问应用程序维护的 CDocTemplate 对象列表，并针对每个文档模板，将条目添加到 Windows 为实现文件关联而维护的注册数据库中。 当用户双击数据文件时，文件管理器会使用这些条目打开该文件。 这样，就无需在应用程序中附带 .REG 文件。

注意

RegisterShellFileTypes 仅在用户使用管理员权限运行程序时有效。 如果程序没有管理员权限，则无法更改注册表项。

如果注册数据库已将给定的文件扩展名与其他文件类型关联，则不会创建新的关联。 有关注册此信息所需的字符串格式，请参阅 CDocTemplate 类。

CWinApp::RegisterWithRestartManager

将应用程序注册到重启管理器。

virtual HRESULT RegisterWithRestartManager(
    BOOL bRegisterRecoveryCallback,
    const CString& strRestartIdentifier);

virtual HRESULT RegisterWithRestartManager(
    LPCWSTR pwzCommandLineArgs,
    DWORD dwRestartFlags,
    APPLICATION_RECOVERY_CALLBACK pRecoveryCallback,
    LPVOID lpvParam,
    DWORD dwPingInterval,
    DWORD dwCallbackFlags);

参数

bRegisterRecoveryCallback
[in] TRUE 表示应用程序的此实例使用恢复回调函数；FALSE 表示它不使用该函数。 当应用程序意外退出时，框架会调用恢复回调函数。 有关详细信息，请参阅 CWinApp::ApplicationRecoveryCallback。

strRestartIdentifier
[in] 标识重启管理器的此实例的唯一字符串。 重启管理器标识符对于应用程序的每个实例都是唯一的。

pwzCommandLineArgs
[in] 包含命令行中任何额外参数的字符串。

dwRestartFlags
[in] 重启管理器的可选标志。 有关详细信息，请参阅“备注”部分。

pRecoveryCallback
[in] 恢复回调函数。 此函数必须采用 LPVOID 参数作为输入并返回 DWORD。 默认恢复回调函数为 CWinApp::ApplicationRecoveryCallback。

lpvParam
[in] 恢复回调函数的输入参数。 有关详细信息，请参阅 CWinApp::ApplicationRecoveryCallback。

dwPingInterval
[in] 重启管理器等待恢复回调函数返回的时长。 此参数以毫秒为单位。

dwCallbackFlags
[in] 传递给恢复回调函数的标志。 保留供将来使用。

返回值

如果方法成功，则为 S_OK；否则为错误代码。

备注

如果应用程序使用默认 MFC 实现自动保存文件，则应使用 RegisterWithRestartManager 的简单版本。 如果要自定义应用程序的自动保存行为，请使用 RegisterWithRestartManager 的复杂版本。

如果使用 strRestartIdentifier 的空字符串调用此方法，RegisterWithRestartManager 会为重启管理器的此实例创建唯一标识符字符串。

当应用程序意外退出时，重启管理器会从命令行重启应用程序，并提供唯一的重启标识符作为可选参数。 在此方案中，框架调用 RegisterWithRestartManager 两次。 第一次调用来自 CWinApp::InitInstance，其中包含字符串标识符的空字符串。 然后，CWinApp::ProcessShellCommand 方法使用唯一重启标识符调用 RegisterWithRestartManager。

将应用程序注册到重启管理器后，重启管理器将监视应用程序。 如果应用程序意外退出，重启管理器会在关闭过程中调用恢复回调函数。 重启管理器会等待 dwPingInterval 以获取恢复回调函数的响应。 如果恢复回调函数在此期间未响应，应用程序会退出而不执行恢复回调函数。

默认情况下，不支持 dwRestartFlags，但供将来使用。 dwRestartFlags 的可能值如下所示：

• RESTART_NO_CRASH

• RESTART_NO_HANG

• RESTART_NO_PATCH

• RESTART_NO_REBOOT

CWinApp::ReopenPreviousFilesAtRestart

确定重启管理器是否重新打开在应用程序意外退出时打开的文件。

virtual BOOL ReopenPreviousFilesAtRestart() const;

返回值

TRUE 表示重启管理器重新打开先前打开的文件；FALSE 表示重启管理器不打开这些文件。

CWinApp::RestartInstance

处理由重启管理器发起的应用程序重启。

virtual BOOL CWinApp::RestartInstance();

返回值

如果数据恢复处理程序打开之前打开的文档，则为 TRUE；如果数据恢复处理程序出错，或者先前没有打开的文档，则为 FALSE。

备注

重启管理器重启应用程序时，框架将调用此方法。 此方法会检索数据恢复处理程序并还原自动保存的文件。 此方法调用 CDataRecoveryHandler::RestoreAutosavedDocuments 来确定用户是否想要还原自动保存的文件。

如果 CDataRecoveryHandler 确定没有打开的文档，则此方法返回 FALSE。 如果没有打开的文档，应用程序通常会启动。

CWinApp::RestoreAutosavedFilesAtRestart

确定重启管理器在重启应用程序时是否还原自动保存的文件。

virtual BOOL RestoreAutosavedFilesAtRestart() const;

返回值

TRUE 表示重启管理器会还原自动保存的文件；FALSE 表示重启管理器不会还原这些文件。

CWinApp::Run

提供默认消息循环。

virtual int Run();

返回值

WinMain 返回的 int 值。

备注

Run 会获取并调度 Windows 消息，直到应用程序接收 WM_QUIT 消息为止。 如果应用程序的消息队列当前不包含任何消息，Run 会调用 OnIdle 来执行空闲时间处理。 传入消息会转到 PreTranslateMessage 成员函数进行特殊处理，然后转到 Windows 函数 TranslateMessage 进行标准键盘转换，最后，调用 Windows 函数 DispatchMessage。

Run 很少被替代，但可替代它来提供特殊行为。

CWinApp::RunAutomated

调用此函数以确定是否存在“/Automation”或“-Automation”选项，它指示服务器应用程序是否由客户端应用程序启动。

BOOL RunAutomated();

返回值

如果找到该选项，则为非零值；否则为 0。

备注

如果存在，则从命令行中移除该选项。 有关 OLE 自动化的详细信息，请参阅自动化服务器一文。

CWinApp::RunEmbedded

调用此函数以确定是否存在“/Embedding”或“-Embedding”选项，它指示服务器应用程序是否由客户端应用程序启动。

BOOL RunEmbedded();

返回值

如果找到该选项，则为非零值；否则为 0。

注解

如果存在，则从命令行中移除该选项。 有关嵌入的详细信息，请参阅服务器：实现服务器一文。

CWinApp::SaveAllModified

由框架调用，以便在即将关闭应用程序的主框架窗口时或通过 WM_QUERYENDSESSION 消息保存所有文档。

virtual BOOL SaveAllModified();

返回值

如果安全终止应用程序，则为非零值；如果无法安全地终止应用程序，则为 0。

备注

对于应用程序中所有已修改的文档，此成员函数的默认实现会依次调用 CDocument::SaveModified 成员函数。

CWinApp::SelectPrinter

调用此成员函数以选择特定打印机，并释放先前在“打印”对话框中选择的打印机。

void SelectPrinter(
    HANDLE hDevNames,
    HANDLE hDevMode,
    BOOL bFreeOld = TRUE);

参数

hDevNames
DEVNAMES 结构的句柄，用于标识特定打印机的驱动程序、设备和输出端口名称。

hDevMode
DEVMODE 结构的句柄，用于指定打印机的设备初始化和环境的相关信息。

bFreeOld
释放先前选定的打印机。

备注

如果 hDevMode 和 hDevNames 均为 NULL，则 SelectPrinter 使用当前的默认打印机。

CWinApp::SetHelpMode

设置应用程序的帮助类型。

void SetHelpMode(AFX_HELP_TYPE eHelpType);

参数

eHelpType
指定要使用的帮助类型。 有关详细信息，请参阅 CWinApp::m_eHelpType。

备注

设置应用程序的帮助类型。

若要将应用程序的帮助类型设置为 HTMLHelp，可以调用 EnableHTMLHelp。 调用 EnableHTMLHelp 后，应用程序必须使用 HTMLHelp 作为其帮助应用程序。 如果要更改以使用 WinHelp，可调用 SetHelpMode 并将 eHelpType 设置为 afxWinHelp。

CWinApp::SetRegistryKey

导致应用程序设置存储在注册表中，而不是 INI 文件中。

void SetRegistryKey(LPCTSTR lpszRegistryKey);
void SetRegistryKey(UINT nIDRegistryKey);

参数

lpszRegistryKey
指向包含项名称的字符串的指针。

nIDRegistryKey
包含注册表项名称的字符串资源的 ID。

注解

此函数会设置 m_pszRegistryKey，它随后由 CWinApp 的 GetProfileInt、GetProfileString、WriteProfileInt 和 WriteProfileString 成员函数使用。 如果已调用此函数，则最近使用的 (MRU) 文件列表也会存储在注册表中。 注册表项通常是公司的名称。 它存储在采用下列格式的项中：HKEY_CURRENT_USER\Software\<company name>\<application name>\<section name>\<value name>。

CWinApp::SupportsApplicationRecovery

确定重启管理器是否恢复意外退出的应用程序。

virtual BOOL SupportsApplicationRecovery() const;

返回值

TRUE 表示重启管理器会恢复应用程序；FALSE 表示重启管理器不会恢复应用程序。

CWinApp::SupportsAutosaveAtInterval

确定重启管理器是否按定期间隔自动保存打开的文档。

virtual BOOL SupportsAutosaveAtInterval() const;

返回值

TRUE 表示重启管理器会自动保存打开的文档；FALSE 表示重启管理器不会自动保存这些文档。

CWinApp::SupportsAutosaveAtRestart

确定重启管理器是否在应用程序重启时自动保存任何打开的文档。

virtual BOOL SupportsAutosaveAtRestart() const;

返回值

TRUE 表示重启管理器会在应用程序重启时自动保存打开的文档；FALSE 表示重启管理器不会自动保存这些文档。

CWinApp::SupportsRestartManager

确定应用程序是否支持重启管理器。

virtual BOOL SupportsRestartManager() const;

返回值

TRUE 表示应用程序支持重启管理器；FALSE 指示应用程序不支持该管理器。

CWinApp::Unregister

取消注册应用程序对象注册的所有文件。

virtual BOOL Unregister();

返回值

若成功，则为非零；否则为 0。

备注

Unregister 函数会撤消应用程序对象和 Register 函数执行的注册。 通常，这两个函数都由 MFC 隐式调用，因此不会显示在代码中。

替代此函数以执行自定义取消注册步骤。

CWinApp::UnregisterShellFileTypes

调用此成员函数，取消应用程序的所有文档类型向 Windows 文件管理器的注册。

void UnregisterShellFileTypes();

CWinApp::WinHelp

调用此成员函数以调用 WinHelp 应用程序。

virtual void WinHelp(
    DWORD_PTR dwData,
    UINT nCmd = HELP_CONTEXT);

参数

dwData
指定其他数据。 使用的值由 nCmd 参数的值决定。

nCmd
指定请求的帮助的类型。 如需可能值的列表并了解这些值如何影响 dwData 参数，请参阅 Windows 函数 WinHelp。

备注

框架还会调用此函数来调用 WinHelp 应用程序。

当应用程序终止时，框架将自动关闭 WinHelp 应用程序。

示例

// Header File: HELPIDS.H
//
// This example header file is #include'd twice:
// (1) It is #include'd by the .CPP file that passes the DWORD
//     context i.d. to CWinApp::WinHelp.
// (2) It is #include'd in the [MAP] section of the .HPJ file,
//     to associate the help context string "HID_MYTOPIC" with
//     the help context numeric i.d., 101.
// The help context string "HID_MYTOPIC" is what identifies the
// help topic in the help .RTF source file, in the "#" footnote:
//     # HID_MYTOPIC
//
// Note, it is not necessary to manage help context id's this way
// for help topics associated with command id's and user interface
// id's defined in your RESOURCE.H file; you should use the MAKEHM
// tool via the custom build rule on your resource.h file to produce
// a help map (.HM) file for these id's.  It is necessary to manage
// help context id's as illustrated here only for help topics not
// associated with command id's or user interface id's.

#define HID_MYTOPIC 101

// Show the custom help topic that has the context string
// "HID_MYTOPIC" in the help .RTF file, and which is mapped
// to the DWORD i.d. HID_MYTOPIC in the above HELPIDS.H file.
AfxGetApp()->WinHelp(HID_MYTOPIC);

// The following is one line of code in the help map (.HM)
// file produced by the MAKEHM tool, which is called by the custom
// build rule on the resource.h file.  The MAKEHM tool reads the
// following #define in the application's RESOURCE.H file:
#define ID_MYCOMMAND 0x08004
// and adds a help id offset value of 0x10000 to create the
// help context DWORD value 0x18004:
// HID_MYCOMMAND                           0x18004
// See MFC Tech Note 28 for more information on help id offset values.

// Rarely will you need to directly call WinHelp yourself
// with the help context i.d. for a command or user interface
// object. The framework will call WinHelp automatically when
// the user, for example, hits F1 when the focus is on a
// My Command menu item. However, if you do want to directly
// call WinHelp for the help topic associated with the command,
// here is how you would do it:

AfxGetApp()->WinHelp(0x10000 + ID_MYCOMMAND);

CWinApp::WriteProfileBinary

调用此成员函数，将二进制数据写入应用程序的注册表或 .INI 文件的指定节。

BOOL WriteProfileBinary(
    LPCTSTR lpszSection,
    LPCTSTR lpszEntry,
    LPBYTE pData,
    UINT nBytes);

参数

lpszSection
指向以 null 结尾的字符串，该字符串指定包含条目的部分。 如果节不存在，则会创建一个。 节名称不区分大小写；字符串可以是大写字母和小写字母的任意组合。

lpszEntry
指向以 null 结尾的字符串，该字符串包含要将值写入到的条目。 如果指定节中不存在该条目，则会创建该条目。

pData
指向要写入的数据的指针。

nBytes
包含要写入的字节数。

返回值

如果成功，则不为 0；否则为 0。

示例

此示例使用 CWinApp* pApp = AfxGetApp(); 来转到 CWinApp 类，从而说明可从 MFC 应用程序中的任何函数使用 WriteProfileBinary 和 GetProfileBinary 的方法。

CWinApp *pApp = AfxGetApp();

CString strSection = _T("My Section");
CString strItem = _T("My Binary Item");
double myData = 123.456e12;

pApp->WriteProfileBinary(strSection, strItem, (LPBYTE)&myData, sizeof(myData));
double *pData;
UINT n;
pApp->GetProfileBinary(strSection, strItem, (LPBYTE*)&pData, &n);
ASSERT(n == sizeof(myData));
ASSERT(myData = *pData);
delete[] pData; // free the buffer

如需其他示例，请参阅 CWinApp::GetProfileBinary 的示例。

CWinApp::WriteProfileInt

调用此成员函数，将指定值写入应用程序的注册表或 .INI 文件的指定节。

BOOL WriteProfileInt(
    LPCTSTR lpszSection,
    LPCTSTR lpszEntry,
    int nValue);

参数

lpszSection
指向以 null 结尾的字符串，该字符串指定包含条目的部分。 如果节不存在，则会创建一个。 节名称不区分大小写；字符串可以是大写字母和小写字母的任意组合。

lpszEntry
指向以 null 结尾的字符串，该字符串包含要将值写入到的条目。 如果指定节中不存在该条目，则会创建该条目。

nValue
包含要写入的值。

返回值

如果成功，则不为 0；否则为 0。

示例

此示例使用 CWinApp* pApp = AfxGetApp(); 来转到 CWinApp 类，从而说明可从 MFC 应用程序中的任何函数使用 WriteProfileString、WriteProfileInt、GetProfileString 和 GetProfileInt 的方法。

CWinApp *pApp = AfxGetApp();

CString strSection = _T("My Section");
CString strStringItem = _T("My String Item");
CString strIntItem = _T("My Int Item");

pApp->WriteProfileString(strSection, strStringItem, _T("test"));

CString strValue;
strValue = pApp->GetProfileString(strSection, strStringItem);
ASSERT(strValue == _T("test"));

pApp->WriteProfileInt(strSection, strIntItem, 1234);

int nValue;
nValue = pApp->GetProfileInt(strSection, strIntItem, 0);
ASSERT(nValue == 1234);

如需其他示例，请参阅 CWinApp::GetProfileInt 的示例。

CWinApp::WriteProfileString

调用此成员函数，将指定的字符串写入应用程序的注册表或 .INI 文件的指定节。

BOOL WriteProfileString(
    LPCTSTR lpszSection,
    LPCTSTR lpszEntry,
    LPCTSTR lpszValue);

参数

lpszSection
指向以 null 结尾的字符串，该字符串指定包含条目的部分。 如果节不存在，则会创建一个。 节名称不区分大小写；字符串可以是大写字母和小写字母的任意组合。

lpszEntry
指向以 null 结尾的字符串，该字符串包含要将值写入到的条目。 如果指定节中不存在该条目，则会创建该条目。 如果此参数为 NULL，则删除 lpszSection 指定的节。

lpszValue
指向要写入的字符串。 如果此参数为 NULL，则删除 lpszEntry 参数指定的条目。

返回值

如果成功，则不为 0；否则为 0。

示例

CWinApp *pApp = AfxGetApp();

CString strSection = _T("My Section");
CString strStringItem = _T("My String Item");
CString strIntItem = _T("My Int Item");

pApp->WriteProfileString(strSection, strStringItem, _T("test"));

CString strValue;
strValue = pApp->GetProfileString(strSection, strStringItem);
ASSERT(strValue == _T("test"));

pApp->WriteProfileInt(strSection, strIntItem, 1234);

int nValue;
nValue = pApp->GetProfileInt(strSection, strIntItem, 0);
ASSERT(nValue == 1234);

如需其他示例，请参阅 CWinApp::GetProfileInt 的示例。

CWinApp::SetAppID

显式设置应用程序的应用程序用户模型 ID。 应在向用户显示任何用户界面之前调用此方法（最佳位置是应用程序构造函数）。

void SetAppID(LPCTSTR lpcszAppID);

参数

lpcszAppID
指定应用程序用户模型 ID。

注解

另请参阅

CWinThread 类
层次结构图
如何：添加重启管理器支持