`CWinAppEx` class

Article
02/25/2022

CWinAppEx handles the application state, saves the state to the registry, loads the state from the registry, initializes application managers, and provides links to those same application managers.

For more detail, see the source code located in the mfc folder of your Visual Studio installation. For example, %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc.

Syntax

class CWinAppEx : public CWinApp

Members

Public Constructors

Name	Description
`CWinAppEx::CWinAppEx`	Constructs a `CWinAppEx` object.

Public Methods

Name	Description
`CWinAppEx::CleanState`	Removes information about the application from the Windows registry.
`CWinAppEx::EnableLoadWindowPlacement`	Specifies whether the application will load the initial size and location of the main frame window from the registry.
`CWinAppEx::EnableTearOffMenus`	Enables tear-off menus for the application.
`CWinAppEx::EnableUserTools`	Enables the user to create custom menu commands in the application.
`CWinAppEx::ExitInstance`	Called by the framework from within the `Run` member function to exit this instance of the application. (Overrides `CWinApp::ExitInstance`.)
`CWinAppEx::GetBinary`	Reads binary data that is associated with the specified registry value.
`CWinAppEx::GetContextMenuManager`	Returns a pointer to the global `CContextMenuManager` object.
`CWinAppEx::GetDataVersion`
`CWinAppEx::GetDataVersionMajor`	Returns the major version of the application saved in the Windows registry.
`CWinAppEx::GetDataVersionMinor`	Returns the minor version of the application saved in the Windows registry.
`CWinAppEx::GetInt`	Reads numeric data that is associated with the specified value from the registry.
`CWinAppEx::GetKeyboardManager`	Returns a pointer to the global `CKeyboardManager` object.
`CWinAppEx::GetMouseManager`	Returns a pointer to the global `CMouseManager` object.
`CWinAppEx::GetObject`	Reads `CObject`-derived data that is associated with the specified value from the registry.
`CWinAppEx::GetRegSectionPath`	Returns a string that is the path of a registry key. This path concatenates the supplied relative path with the application path.
`CWinAppEx::GetRegistryBase`	Returns the registry path for the application.
`CWinAppEx::GetSectionBinary`	Reads binary data that is associated with the specified key and value from the registry.
`CWinAppEx::GetSectionInt`	Reads numeric data from the registry associated with the specified key and value.
`CWinAppEx::GetSectionObject`	Reads `CObject` data that is associated with the specified key and value from the registry.
`CWinAppEx::GetSectionString`	Reads string data that is associated with the specified key and value from the registry.
`CWinAppEx::GetShellManager`	Returns a pointer to the global `CShellManager` object.
`CWinAppEx::GetString`	Reads string data that is associated with the specified value from the registry.
`CWinAppEx::GetTooltipManager`	Returns a pointer to the global `CTooltipManager` object.
`CWinAppEx::GetUserToolsManager`	Returns a pointer to the global `CUserToolsManager` object.
`CWinAppEx::InitContextMenuManager`	Initializes the `CContextMenuManager` object.
`CWinAppEx::InitKeyboardManager`	Initializes the `CKeyboardManager` object.
`CWinAppEx::InitMouseManager`	Initializes the `CMouseManager` object.
`CWinAppEx::InitShellManager`	Initializes the `CShellManager` class
`CWinAppEx::InitTooltipManager`	Initializes the `CTooltipManager` class.
`CWinAppEx::IsResourceSmartUpdate`
`CWinAppEx::IsStateExists`	Indicates whether the specified key is in the registry.
`CWinAppEx::LoadState`	Loads the application state from the registry.
`CWinAppEx::OnAppContextHelp`	Called by the framework when the user requests context help for the Customization dialog box.
`CWinAppEx::OnViewDoubleClick`	Calls the user-defined command when the user double-clicks anywhere in the application.
`CWinAppEx::OnWorkspaceIdle`
`CWinAppEx::SaveState`	Writes the state of the application framework to the Windows registry.
`CWinAppEx::SetRegistryBase`	Sets the path of the default registry key. This key will serve as a root for all subsequent registry calls.
`CWinAppEx::ShowPopupMenu`	Displays a popup menu.
`CWinAppEx::WriteBinary`	Writes the binary data to the specified registry value.
`CWinAppEx::WriteInt`	Writes the numeric data to the specified registry value.
`CWinAppEx::WriteObject`	Writes data that is derived from the `CObject` Class to the specified registry value.
`CWinAppEx::WriteSectionBinary`	Writes the binary data to a value of the specified registry key.
`CWinAppEx::WriteSectionInt`	Writes the numeric data to a value of the specified registry key.
`CWinAppEx::WriteSectionObject`	Writes data derived from the `CObject` class to a value of the specified registry key.
`CWinAppEx::WriteSectionString`	Writes the string data to a value of the specified registry key.
`CWinAppEx::WriteString`	Writes the string data to the specified registry value.

Protected Methods

Name	Description
`CWinAppEx::LoadCustomState`	Called by the framework when the application state has been loaded.
`CWinAppEx::LoadWindowPlacement`	Called by the framework when it loads the size and location of your application from the registry. The loaded data includes the size and location of the main frame at the time your application last closed.
`CWinAppEx::OnClosingMainFrame`	Called by the framework when a main frame window is processing `WM_CLOSE`.
`CWinAppEx::PreLoadState`	Called by the framework immediately before the application state is loaded.
`CWinAppEx::PreSaveState`	Called by the framework immediately before the application state is saved.
`CWinAppEx::ReloadWindowPlacement`	Reloads the size and location of the supplied window from the registry
`CWinAppEx::SaveCustomState`	Called by the framework after it writes the application state to the registry.
`CWinAppEx::StoreWindowPlacement`	Called by the framework to write the size and location of the main frame to the registry.

Data Members

Name	Description
`CWinAppEx::m_bForceImageReset`	Specifies whether the framework will reset all toolbar images when the frame window that contains the toolbar is loaded.

Remarks

Much of the functionality provided by the MFC framework depends on the CWinAppEx class. You can incorporate the CWinAppEx class into your application in one of two ways:

Construct a CWinAppEx class in the main thread.
Derive the main application class from CWinAppEx.

After you incorporate CWinAppEx into your application, you can initialize any one of the application managers. Before you use an application manager, you must initialize it by calling the appropriate initialize method. To obtain a pointer to a specific manager, call the associated get method. The CWinAppEx class manages the following application managers: CMouseManager Class, CContextMenuManager Class, CKeyboardManager Class, CUserToolsManager Class, and CMenuTearOffManager Class.

Inheritance Hierarchy

Requirements

Header: afxwinappex.h

`CWinAppEx::CleanState`

Removes all the information about the application from the Windows registry.

virtual BOOL CleanState(LPCTSTR lpszSectionName=NULL);

Parameters

lpszSectionName
[in] A string that contains a path of a registry key.

Return Value

Nonzero if the method was successful; otherwise 0.

Remarks

This method clears application data from a specific section of the registry. You can specify the section to clear by using the parameter lpszSectionName. If lpszSectionName is NULL, this method will use the default registry path stored in the CWinAppEx object. To get the default registry path, use CWinAppEx::GetRegistryBase.

`CWinAppEx::CWinAppEx`

Constructs a CWinAppEx object.

CWinAppEx(BOOL bResourceSmartUpdate = FALSE);

Parameters

bResourceSmartUpdate
[in] A Boolean parameter that specifies whether the workspace object should detect and handle resource updates.

Remarks

The CWinAppEx class has initialization methods, provides functionality for saving and loading application information to the registry, and controls global application settings. It also enables you to use global managers such as the CKeyboardManager Class and the CUserToolsManager Class. Each application can have only one instance of the CWinAppEx class.

`CWinAppEx::EnableLoadWindowPlacement`

Specifies whether the application will load the initial size and location of the main frame window from the registry.

void EnableLoadWindowPlacement(BOOL bEnable = TRUE);

Parameters

bEnable
[in] Specifies whether the application loads the initial size and location of the main frame window from the registry.

Remarks

By default, the size and location of the main frame is loaded from the registry together with other application settings. This occurs during CWinAppEx::LoadState. If you don't want to load the initial window placement from the registry, call this method with bEnable set to FALSE.

`CWinAppEx::EnableTearOffMenus`

Creates and initializes a CMenuTearOffManager object.

BOOL EnableTearOffMenus(
    LPCTSTR lpszRegEntry,
    const UINT uiCmdFirst,
    const UINT uiCmdLast);

Parameters

lpszRegEntry
[in] A string that contains the path of a registry key. The application uses this registry key to store information for the tear-off menus.

uiCmdFirst
[in] The first tear off menu ID.

uiCmdLast
[in] The last tear off menu ID.

Return Value

TRUE if the CMenuTearOffManager is created and initialized successfully; FALSE if an error occurs or if the CMenuTearOffManager already exists.

Remarks

Use this function to enable tear-off menus in your application. You should call this function from InitInstance.

`CWinAppEx::EnableUserTools`

Enables the user to create custom menu commands that reduce keystrokes in your application. This method creates a CUserToolsManager object.

BOOL EnableUserTools(
    const UINT uiCmdToolsDummy,
    const UINT uiCmdFirst,
    const UINT uiCmdLast,
    CRuntimeClass* pToolRTC = RUNTIME_CLASS(CUserTool),
    UINT uArgMenuID = 0,
    UINT uInitDirMenuID = 0);

Parameters

uiCmdToolsDummy
[in] An unsigned integer that the framework uses as a placeholder for the command ID of the user tools menu.

uiCmdFirst
[in] The command ID for the first user tool command.

uiCmdLast
[in] The command ID for the last user tool command.

pToolRTC
[in] A class that the CUserToolsManager object uses to create new user tools.

uArgMenuID
[in] The argument menu ID.

uInitDirMenuID
[in] The menu ID for the initial tool directory.

Return Value

TRUE if the method creates and initializes a CUserToolsManager object; FALSE if the method fails or if a CUserToolsManager object already exists.

Remarks

When you enable user-defined tools, the framework automatically supports a dynamic menu that can be extended during customization. The framework associates each new item with an external command. The framework invokes these commands when the user selects the appropriate item from the Tools menu.

Every time the user adds a new item, the framework creates a new object. The class type for the new object is defined by pToolRTC. The pToolRTC class type must be derived from the CUserTool Class.

For more information about user tools and how to incorporate them into your application, see User-defined Tools.

`CWinAppEx::ExitInstance`

virtual int ExitInstance();

Return Value

Remarks

`CWinAppEx::GetBinary`

Reads binary data from a specified registry key.

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

Parameters

lpszEntry
[in] A string that contains the name of a registry key.

ppData
[out] A pointer to the buffer that the method fills with the binary data.

pBytes
[out] A pointer to an unsigned integer that the method uses to write the number of bytes read.

Return Value

TRUE if successful; FALSE otherwise.

Remarks

This method reads binary data written to the registry. To write data to the registry, use the methods CWinAppEx::WriteBinary and CWinAppEx::WriteSectionBinary.

The lpszEntry parameter is the name of a registry entry located under the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

`CWinAppEx::GetContextMenuManager`

Returns a pointer to the global CContextMenuManager object.

CContextMenuManager* GetContextMenuManager();

Return Value

A pointer to the global CContextMenuManager object.

Remarks

If the CContextMenuManager object isn't initialized, this function calls CWinAppEx::InitContextMenuManager before it returns a pointer.

`CWinAppEx::GetDataVersion`

int GetDataVersion() const;

Return Value

Remarks

`CWinAppEx::GetDataVersionMajor`

Returns the major version of the application that is saved in the Windows registry when you call CWinAppEx::SaveState.

int GetDataVersionMajor() const;

Return Value

An integer value that contains the major version number.

`CWinAppEx::GetDataVersionMinor`

Returns the minor version of the application that is saved in the Windows registry when you call CWinAppEx::SaveState.

int GetDataVersionMinor() const;

Return Value

An integer value that contains the minor version number.

`CWinAppEx::GetInt`

Reads integer data from a specified registry key.

int GetInt(
    LPCTSTR lpszEntry,
    int nDefault = 0);

Parameters

lpszEntry
[in] A string that contains the name of a registry entry.

nDefault
[in] The default value that the method returns if the specified registry entry doesn't exist.

Return Value

The registry data if the method was successful; otherwise nDefault.

Remarks

This method reads integer data from the registry. If there's no integer data associated with the registry key indicated by lpszEntry, this method returns nDefault. To write data to the registry, use the methods CWinAppEx::WriteSectionInt and CWinAppEx::WriteInt.

`CWinAppEx::GetKeyboardManager`

Returns a pointer to the global CKeyboardManager object.

CKeyboardManager* GetKeyboardManager();

Return Value

A pointer to the global CKeyboardManager object.

Remarks

If the keyboard manager isn't initialized, this function calls CWinAppEx::InitKeyboardManager before it returns a pointer.

`CWinAppEx::GetMouseManager`

Returns a pointer to the global CMouseManager object.

CMouseManager* GetMouseManager();

Return Value

A pointer to the global CMouseManager object.

Remarks

If the mouse manager isn't initialized, this function calls CWinAppEx::InitMouseManager before it returns a pointer.

`CWinAppEx::GetObject`

Reads CObject-dervied data from the registry.

BOOL GetObject(
    LPCTSTR lpszEntry,
    CObject& obj);

Parameters

lpszEntry
[in] A string that contains the relative path of a registry entry.

obj
[out] A reference to a CObject. The method uses this reference to store the registry data.

Return Value

Nonzero if the method was successful; otherwise 0.

Remarks

This method reads data from the registry that is derived from CObject. To write CObject data to the registry, use either CWinAppEx::WriteObject or CWinAppEx::WriteSectionObject.

The lpszEntry parameter is the name of a registry entry that is located under the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

`CWinAppEx::GetRegistryBase`

Retrieves the default registry path for the application.

LPCTSTR GetRegistryBase();

Return Value

A string that contains the path of the default registry location.

Remarks

All methods of the CWinAppEx Class that access the registry start in a default location. Use this method to retrieve a path of the default registry location. Use CWinAppEx::SetRegistryBase to change the default registry location.

`CWinAppEx::GetRegSectionPath`

Creates and returns the absolute path of a registry key.

CString GetRegSectionPath(LPCTSTR szSectionAdd = _T(""));

Parameters

szSectionAdd
[in] A string that contains the relative path of a registry key.

Return Value

A CString that contains the absolute path of a registry key.

Remarks

This method defines the registry key's absolute path by appending the relative path in szSectionAdd to the default registry location for your application. To get the default registry key, use the method CWinAppEx::GetRegistryBase.

`CWinAppEx::GetSectionBinary`

Reads binary data from the registry.

BOOL GetSectionBinary(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    LPBYTE* ppData,
    UINT* pBytes);

Parameters

lpszSubSection
[in] A string that contains the relative path of a registry key.

lpszEntry
[in] A string that contains the value to read.

ppData
[out] A pointer to the buffer where the method stores the data.

pBytes
[out] A pointer to an unsigned integer. The method writes the size of ppData to this parameter.

Return Value

TRUE if successful; otherwise FALSE.

Remarks

This method reads binary data that is written to the registry using the methods CWinAppEx::WriteBinary and CWinAppEx::WriteSectionBinary.

The lpszSubSection parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

`CWinAppEx::GetSectionInt`

Reads integer data from the registry.

int GetSectionInt(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    int nDefault = 0);

Parameters

lpszSubSection
[in] A string that contains the relative path of a registry key.

lpszEntry
[in] A string that contains the value to read.

nDefault
[in] The default value to return if the specified value doesn't exist.

Return Value

The integer data that is stored in the specified registry value; nDefault if the data doesn't exist.

Remarks

Use the methods CWinAppEx::WriteInt and CWinAppEx::WriteSectionInt to write integer data to the registry.

The lpszSubSection parameter isn't an absolute path of a registry entry. It's a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

`CWinAppEx::GetSectionObject`

Reads CObject registry data from the registry.

BOOL GetSectionObject(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    CObject& obj);

Parameters

lpszSubSection
[in] A string that contains the relative path of a registry key.

lpszEntry
[in] A string that contains the value to read.

obj
[out] A reference to a CObject. The method uses this CObject to store the registry data.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This method reads data from the registry. The data read is CObject data, or data for a class derived from CObject. To write CObject data to the registry, use either CWinAppEx::WriteObject or CWinAppEx::WriteSectionObject.

`CWinAppEx::GetSectionString`

Reads string data from the registry.

CString GetSectionString(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    LPCTSTR lpszDefault = _T(""));

Parameters

lpszSubSection
[in] A string that contains the relative path of a registry key.

lpszEntry
[in] A string that contains the value to read.

lpszDefault
[in] The default value to return if the specified value doesn't exist.

Return Value

The string data stored in the specified registry value if the data exists; otherwise lpszDefault.

Remarks

This method reads string data written to the registry. Use CWinAppEx::WriteString and CWinAppEx::WriteSectionString to write string data to the registry.

`CWinAppEx::GetShellManager`

Returns a pointer to the global CShellManager object.

CShellManager* GetShellManager();

Return Value

A pointer to the global CShellManager object.

Remarks

If the CShellManager object isn't initialized, this function calls CWinAppEx::InitShellManager before it returns a pointer.

`CWinAppEx::GetString`

Reads string data from a specified registry key.

CString GetString(
    LPCTSTR lpszEntry,
    LPCTSTR lpzDefault= _T(""));

Parameters

lpszEntry
[in] A string that contains the name of a registry key

lpzDefault
[in] The default value that the method returns if the specified registry entry doesn't exist.

Return Value

The string data stored in the registry if successful; lpszDefault otherwise.

Remarks

This method reads string data written to the registry. To write data to the registry, use the methods CWinAppEx::WriteString or CWinAppEx::WriteSectionString.

`CWinAppEx::GetTooltipManager`

Returns a pointer to the global CTooltipManager object.

CTooltipManager* GetTooltipManager();

Return Value

A pointer to the global CTooltipManager object.

Remarks

If the CTooltipManager object isn't initialized, this function calls CWinAppEx::InitTooltipManager before it returns a pointer.

`CWinAppEx::GetUserToolsManager`

Returns a pointer to the global CUserToolsManager object.

CUserToolsManager* GetUserToolsManager();

Return Value

A pointer to the global CUserToolsManager object; NULL if user tools management isn't enabled for the application.

Remarks

Before you retrieve a pointer to the CUserToolsManager object, you must initialize the manager by calling CWinAppEx::EnableUserTools.

`CWinAppEx::InitContextMenuManager`

Initializes the CContextMenuManager object.

BOOL InitContextMenuManager();

Return Value

Nonzero if the method creates the CContextMenuManager object; 0 if the CContextMenuManager object already exists.

Remarks

If you call CWinAppEx::GetContextMenuManager, the default implementation of that method calls InitContextMenuManager.

If your application already has a context menu manager and you call InitContextMenuManager, your application will have an ASSERT failure. Therefore, you shouldn't call InitContextMenuManager if you create a CContextMenuManager object directly. If you aren't using a custom CContextMenuManager, you should use GetContextMenuManager to create a CContextMenuManager object.

`CWinAppEx::InitKeyboardManager`

Initializes the CKeyboardManager object.

BOOL InitKeyboardManager();

Return Value

Nonzero if the method creates the CKeyboardManager object; 0 if the CKeyboardManager object already exists.

Remarks

If you call CWinAppEx::GetKeyboardManager, the default implementation of that method calls InitKeyboardManager.

If your application already has a keyboard manager and you call InitKeyboardManager, your application will have an ASSERT failure. Therefore, you shouldn't call InitKeyboardManager if you create a CKeyboardManager object directly. If you aren't using a custom CKeyboardManager, you should use GetKeyboardManager to create a CKeyboardManager object.

`CWinAppEx::InitMouseManager`

Initializes the CMouseManager object.

BOOL InitMouseManager();

Return Value

Nonzero if the method creates the CMouseManager object; 0 if the CMouseManager object already exists.

Remarks

If you call CWinAppEx::GetMouseManager, the default implementation of that method calls InitMouseManager.

If your application already has a mouse manager and you call InitMouseManager, your application will have an ASSERT failure. Therefore you shouldn't call InitMouseManager if you create a CMouseManager object directly. If you aren't using a custom CMouseManager, you should use GetMouseManager to create a CMouseManager object.

`CWinAppEx::InitShellManager`

Initializes the CShellManager object.

BOOL InitShellManager();

Return Value

Nonzero if the method creates the CShellManager object; 0 if the CShellManager object already exists.

Remarks

If you call CWinAppEx::GetShellManager, the default implementation of that method calls InitShellManager.

If your application already has a shell manager and you call InitShellManager, your application raises an ASSERT failure. Therefore, don't call InitShellManager if you create a CShellManager object directly. If you aren't using a custom CShellManager, use GetShellManager to create a CShellManager object.

`CWinAppEx::InitTooltipManager`

Initializes the CTooltipManager object.

BOOL InitTooltipManager();

Return Value

Nonzero if the method creates the CTooltipManager object; 0 if the CTooltipManager object already exists.

Remarks

If you call CWinAppEx::GetTooltipManager, the default implementation of that method calls InitTooltipManager.

If your application already has a tooltip manager and you call InitTooltipManager, your application will have an ASSERT failure. Therefore, you shouldn't call InitTooltipManager if you create a CTooltipManager object directly. If you aren't using a custom CTooltipManager, you should use GetTooltipManager to create a CTooltipManager object.

`CWinAppEx::IsResourceSmartUpdate`

BOOL IsResourceSmartUpdate() const;

Return Value

Remarks

`CWinAppEx::IsStateExists`

Indicates whether the specified key is in the registry.

BOOL IsStateExists(LPCTSTR lpszSectionName);

Parameters

lpszSectionName
[in] A string that contains a path of a registry key.

Return Value

Nonzero if the key is in the registry; otherwise 0.

`CWinAppEx::LoadCustomState`

The framework calls this method after it loads the state of the application from the registry.

virtual void LoadCustomState();

Remarks

Override this method if you want to do any processing after the application loads the state from the registry. By default, this method does nothing.

In order to load custom state information from the registry, the information must first be saved by using CWinAppEx::SaveCustomState.

`CWinAppEx::LoadState`

Reads the application state from the Windows registry.

BOOL LoadState(
    CMDIFrameWndEx* pFrame,
    LPCTSTR lpszSectionName = NULL);

BOOL LoadState(
    CFrameWndEx* pFrame,
    LPCTSTR lpszSectionName = NULL);

BOOL LoadState(
    COleIPFrameWndEx* pFrame,
    LPCTSTR lpszSectionName = NULL);

virtual BOOL LoadState(
    LPCTSTR lpszSectionName = NULL,
    CFrameImpl* pFrameImpl = NULL);

Parameters

pFrame
[in] A pointer to a frame window object. The method applies the state information in the registry to this frame window.

lpszSectionName
[in] A string that contains the relative path of a registry key.

pFrameImpl
[in] A pointer to a CFrameImpl object. The method applies the state information in the registry to this frame window.

Return Value

Nonzero if successful; 0 otherwise.

Remarks

This method loads the state of the application and any state information for a frame window. The loaded information for the frame window is applied to the supplied frame window. If you don't supply a frame window, only the application state information is loaded. The application information includes the state of the CMouseManager Class, CContextMenuManager Class, CKeyboardManager Class, and the CUserToolsManager Class.

The default implementation of CFrameImpl::OnLoadFrame calls LoadState.

The lpszSectionName parameter isn't the absolute path for a registry entry. It's a relative path that is added to the end of the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

`CWinAppEx::LoadWindowPlacement`

Called by the framework when it loads the size and location of the main frame window from the registry.

virtual BOOL LoadWindowPlacement(
    CRect& rectNormalPosition,
    int& nFlags,
    int& nShowCmd);

Parameters

rectNormalPosition
[out] A rectangle that contains the coordinates of the main frame window when it is in the restored position.

nFlags
[out] Flags that control the position of the minimized window and how the operating system switches between a minimized window and a restored window.

nShowCmd
[out] An integer that specifies the show state of the window. For more information about possible values, see CWnd::ShowWindow.

Return Value

Nonzero if successful; 0 otherwise.

Remarks

By default, MFC automatically loads the previous position and state of the main frame window when the application starts. For more information about how this information is stored in the registry, see CWinAppEx::StoreWindowPlacement.

Override this method if you want to load additional information about the main frame window.

`CWinAppEx::m_bForceImageReset`

Specifies whether the framework resets all toolbar images when it reloads the frame window that contains the toolbar.

BOOL m_bForceImageReset;

Remarks

The m_bForceImageReset data member is a protected variable.

`CWinAppEx::OnAppContextHelp`

The framework calls this method when the user requests context help for the Customization dialog box.

virtual void OnAppContextHelp(
    CWnd* pWndControl,
    const DWORD dwHelpIDArray[]);

Parameters

pWndControl
[in] A pointer to a window object for which the user invoked context help.

dwHelpIDArray[]
[in] A reserved value.

Remarks

This method is currently reserved for future use. The default implementation does nothing and it's currently not called by the framework.

`CWinAppEx::OnClosingMainFrame`

The framework calls this method when a frame window is processing WM_CLOSE.

virtual void OnClosingMainFrame(CFrameImpl* pFrameImpl);

Parameters

pFrameImpl
[in] A pointer to a CFrameImpl object.

Remarks

The default implementation of this method saves the state of pFrameImpl.

`CWinAppEx::OnViewDoubleClick`

Calls the user-defined command that is associated with a view when the user double-clicks anywhere within that view.

virtual BOOL OnViewDoubleClick(
    CWnd* pWnd,
    int iViewId);

Parameters

pWnd
[in] A pointer to an object derived from the CView Class.

iViewId
[in] The view ID.

Return Value

TRUE if the framework finds a command; otherwise FALSE.

Remarks

In order to support custom mouse behavior, you must call this function when you process the WM_LBUTTONDBLCLK message. This method will execute the command associated with the view ID supplied by iViewId. For more information about custom mouse behavior, see Keyboard and Mouse Customization.

`CWinAppEx::OnWorkspaceIdle`

virtual BOOL OnWorkspaceIdle(CWnd*);

Parameters

[in] CWnd*\

Return Value

Remarks

`CWinAppEx::PreLoadState`

The framework calls this method immediately before it loads the state of the application from the registry.

virtual void PreLoadState();

Remarks

Override this method if you want to do any processing immediately before the framework loads the application state.

`CWinAppEx::PreSaveState`

The framework calls this method immediately before it saves the application state.

virtual void PreSaveState();

Remarks

Override this method if you want to do any processing immediately before the framework saves the application state.

`CWinAppEx::ReloadWindowPlacement`

Reloads the size and location of a window from the registry.

virtual BOOL ReloadWindowPlacement(CFrameWnd* pFrame);

Parameters

pFrame
[in] A pointer to a frame window.

Return Value

Nonzero if the method was successful; 0 if the load failed or there's no data to load.

Remarks

Use the function CWinAppEx::StoreWindowPlacement to write the size and location of a window to the registry.

`CWinAppEx::SaveCustomState`

The framework calls this method after it saves the state of the application to the registry.

virtual void SaveCustomState();

Remarks

Override this method if you want to do any processing after the application saves the state to the registry. By default, this method does nothing.

`CWinAppEx::SaveState`

Writes the application state to the Windows registry.

virtual BOOL SaveState(
    LPCTSTR lpszSectionName = NULL,
    CFrameImpl* pFrameImpl = NULL);

BOOL SaveState(
    CMDIFrameWndEx* pFrame,
    LPCTSTR lpszSectionName = NULL);

BOOL SaveState(
    CFrameWndEx* pFrame,
    LPCTSTR lpszSectionName = NULL);

BOOL SaveState(
    COleIPFrameWndEx* pFrame,
    LPCTSTR lpszSectionName = NULL);

Parameters

lpszSectionName
[in] A string that contains the relative path of a registry key.

pFrameImpl
[in] A pointer to a CFrameImpl object. This frame is saved to the Windows registry.

pFrame
[in] A pointer to a frame window object. This frame is saved to the Windows registry.

Return Value

TRUE if successful; FALSE otherwise.

Remarks

This method saves the state of the application and any state information for the provided frame window. If you don't provide a frame window, the method only saves the application state. The application information includes the state of the CMouseManager Class, CContextMenuManager Class, CKeyboardManager Class, and the CUserToolsManager Class.

The lpszSectionName parameter isn't the absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

`CWinAppEx::SetRegistryBase`

Sets the default registry path for the application.

LPCTSTR SetRegistryBase(LPCTSTR lpszSectionName = NULL);

Parameters

lpszSectionName
[in] A string that contains the path of a registry key.

Return Value

A string that contains the path of the default registry location.

Remarks

All methods of the CWinAppEx Class that access the registry start in a default location. Use this method to change that default registry location. Use CWinAppEx::GetRegistryBase to retrieve the default registry location.

`CWinAppEx::ShowPopupMenu`

Displays a popup menu.

virtual BOOL ShowPopupMenu(
    UINT uiMenuResId,
    const CPoint& point,
    CWnd* pWnd);

Parameters

uiMenuResId
[in] A menu resource ID.

point
[in] A CPoint that specifies the position of the menu in screen coordinates.

pWnd
[in] A pointer to the window that owns the popup menu.

Return Value

Nonzero if the popup menu is displayed successfully; 0 otherwise.

Remarks

This method displays the menu associated with uiMenuResId.

To support popup menus, you must have a CContextMenuManager object. If you haven't initialized the CContextMenuManager object, ShowPopupMenu will fail.

`CWinAppEx::StoreWindowPlacement`

Called by the framework to write the size and location of the main frame window to the registry.

virtual BOOL StoreWindowPlacement(
    const CRect& rectNormalPosition,
    int nFlags,
    int nShowCmd);

Parameters

nFlags
[in] Flags that control the position of the minimized window and how the operating system switches between a minimized window and a restored window.

nShowCmd
[in] An integer that specifies the show state of the window. For more information about possible values, see CWnd::ShowWindow.

rectNormalPosition
[in] A rectangle that contains the coordinates of the main frame window when it is in the restored state.

Return Value

Nonzero if successful; 0 otherwise.

Remarks

By default, MFC automatically saves the position and state of the main frame window before the application exits. This information is stored in the Windows registry under the WindowPlacement key in the default registry location for your application. For more information about the default registry location of your application, see CWinAppEx::GetRegistryBase.

Override this method if you want to store additional information about the main frame window.

`CWinAppEx::WriteBinary`

Writes binary data to the registry.

BOOL WriteBinary(
    LPCTSTR lpszEntry,
    LPBYTE pData,
    UINT nBytes);

Parameters

lpszEntry
[in] A string that contains the name of a registry key.

pData
[in] The data to store.

nBytes
[in] The size of pData in bytes.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

If the key specified by lpszEntry doesn't exist, this method will create it.

`CWinAppEx::WriteInt`

Writes numeric data to the registry.

BOOL WriteInt(
    LPCTSTR lpszEntry,
    int nValue);

Parameters

lpszEntry
[in] A string that contains the name of a registry key.

nValue
[in] The data to store.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

If the key specified by lpszEntry doesn't exist, this method will create it.

`CWinAppEx::WriteObject`

Writes data derived from the CObject Class to the registry.

BOOL WriteObject(
    LPCTSTR lpszEntry,
    CObject& obj);

Parameters

lpszEntry
[in] A string that contains the value to set.

obj
[in] A reference to CObject data that the method will store.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

This method writes the obj data to the specified value under the default registry key. Use CWinAppEx::GetRegistryBase to determine the current registry key.

`CWinAppEx::WriteSectionBinary`

Writes binary data to a value in the registry.

BOOL WriteSectionBinary(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    LPBYTE pData,
    UINT nBytes);

Parameters

lpszSubSection
[in] A string that contains the name of a registry key

lpszEntry
[in] A string that contains the value to set.

pData
[in] The data to write to the registry.

nBytes
[in] The size of pData in bytes.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

The lpszSubSection parameter isn't the absolute path for a registry entry. It's a relative path that is appended to the end of the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

If the key specified by lpszEntry doesn't exist, this method will create it.

`CWinAppEx::WriteSectionInt`

Writes numeric data to the registry.

BOOL WriteSectionInt(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    int nValue);

Parameters

lpszSubSection
[in] A string that contains the relative path of a registry key.

lpszEntry
[in] A string that contains the value to set.

nValue
[in] The data to write to the registry.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

The lpszSubSection parameter isn't an absolute path for a registry entry. It's a relative path that is appended to the default registry key for your application. To get or set the default registry key, use the methods CWinAppEx::GetRegistryBase and CWinAppEx::SetRegistryBase respectively.

If the key specified by lpszEntry doesn't exist, this method will create it.

`CWinAppEx::WriteSectionObject`

Writes data derived from the CObject Class to a specific registry value.

BOOL WriteSectionObject(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    CObject& obj);

Parameters

lpszSubSection
[in] A string that contains the name of a registry key.

lpszEntry
[in] A string that contains the name of the value to set.

obj
[in] The data to store.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

If the value specified by lpszEntry doesn't exist under the registry key specified by lpszSubSection, this method will create that value.

`CWinAppEx::WriteSectionString`

Writes string data to a value in the registry.

BOOL WriteSectionString(
    LPCTSTR lpszSubSection,
    LPCTSTR lpszEntry,
    LPCTSTR lpszValue);

Parameters

lpszSubSection
[in] A string that contains the name of a registry key.

lpszEntry
[in] A string that contains the value to set.

lpszValue
[in] The string data to write to the registry.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

If the value specified by lpszEntry doesn't exist under lpszSubSection, this method will create it.

`CWinAppEx::WriteString`

Writes string data to the registry.

BOOL WriteString(
    LPCTSTR lpszEntry,
    LPCTSTR lpszValue);

Parameters

lpszEntry
[in] A string that contains the name of a registry key.

lpszValue
[in] The data to store.

Return Value

TRUE if this method is successful; otherwise FALSE.

Remarks

If the key specified by lspzEntry doesn't exist, this method will create it.

Share via

CWinAppEx class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Data Members

Remarks

Inheritance Hierarchy

Requirements

CWinAppEx::CleanState

Parameters

Return Value

Remarks

CWinAppEx::CWinAppEx

Parameters

Remarks

CWinAppEx::EnableLoadWindowPlacement

Parameters

Remarks

CWinAppEx::EnableTearOffMenus

Parameters

Return Value

Remarks

CWinAppEx::EnableUserTools

Parameters

Return Value

Remarks

CWinAppEx::ExitInstance

Return Value

Remarks

CWinAppEx::GetBinary

Parameters

Return Value

Remarks

CWinAppEx::GetContextMenuManager

Return Value

Remarks

CWinAppEx::GetDataVersion

Return Value

Remarks

CWinAppEx::GetDataVersionMajor

Return Value

CWinAppEx::GetDataVersionMinor

Return Value

CWinAppEx::GetInt

Parameters

Return Value

Remarks

CWinAppEx::GetKeyboardManager

Return Value

Remarks

CWinAppEx::GetMouseManager

Return Value

Remarks

CWinAppEx::GetObject

Parameters

Return Value

Remarks

CWinAppEx::GetRegistryBase

Return Value

Remarks

CWinAppEx::GetRegSectionPath

Parameters

Return Value

Remarks

CWinAppEx::GetSectionBinary

Parameters

Return Value

Remarks

CWinAppEx::GetSectionInt

Parameters

Return Value

Remarks

CWinAppEx::GetSectionObject

Parameters

Return Value

Remarks

CWinAppEx::GetSectionString

`CWinAppEx` class

`CWinAppEx::CleanState`

`CWinAppEx::CWinAppEx`

`CWinAppEx::EnableLoadWindowPlacement`

`CWinAppEx::EnableTearOffMenus`

`CWinAppEx::EnableUserTools`

`CWinAppEx::ExitInstance`

`CWinAppEx::GetBinary`

`CWinAppEx::GetContextMenuManager`

`CWinAppEx::GetDataVersion`

`CWinAppEx::GetDataVersionMajor`

`CWinAppEx::GetDataVersionMinor`

`CWinAppEx::GetInt`

`CWinAppEx::GetKeyboardManager`

`CWinAppEx::GetMouseManager`

`CWinAppEx::GetObject`

`CWinAppEx::GetRegistryBase`

`CWinAppEx::GetRegSectionPath`

`CWinAppEx::GetSectionBinary`

`CWinAppEx::GetSectionInt`

`CWinAppEx::GetSectionObject`

`CWinAppEx::GetSectionString`

`CWinAppEx::GetShellManager`

`CWinAppEx::GetString`

`CWinAppEx::GetTooltipManager`

`CWinAppEx::GetUserToolsManager`

`CWinAppEx::InitContextMenuManager`

`CWinAppEx::InitKeyboardManager`

`CWinAppEx::InitMouseManager`

`CWinAppEx::InitShellManager`

`CWinAppEx::InitTooltipManager`

`CWinAppEx::IsResourceSmartUpdate`

`CWinAppEx::IsStateExists`

`CWinAppEx::LoadCustomState`

`CWinAppEx::LoadState`

`CWinAppEx::LoadWindowPlacement`

`CWinAppEx::m_bForceImageReset`

`CWinAppEx::OnAppContextHelp`

`CWinAppEx::OnClosingMainFrame`

`CWinAppEx::OnViewDoubleClick`

`CWinAppEx::OnWorkspaceIdle`

`CWinAppEx::PreLoadState`

`CWinAppEx::PreSaveState`

`CWinAppEx::ReloadWindowPlacement`