Public Data Members

A CWnd object is distinct from a Windows window, but the two are tightly linked. A CWnd object is created or destroyed by the CWnd constructor and destructor. The Windows window, on the other hand, is a data structure internal to Windows that is created by a Create member function and destroyed by the CWnd virtual destructor. The DestroyWindow function destroys the Windows window without destroying the object.

The CWnd class and the message-map mechanism hide the WndProc function. Incoming Windows notification messages are automatically routed through the message map to the proper OnMessageCWnd member functions. You override an OnMessage member function to handle a member's particular message in your derived classes.

The CWnd class also lets you create a Windows child window for your application. Derive a class from CWnd, then add member variables to the derived class to store data specific to your application. Implement message-handler member functions and a message map in the derived class to specify what happens when messages are directed to the window.

You create a child window in two steps. First, call the constructor CWnd to construct the CWnd object, then call the Create member function to create the child window and attach it to the CWnd object.

When the user terminates your child window, destroy the CWnd object, or call the DestroyWindow member function to remove the window and destroy its data structures.

Within the Microsoft Foundation Class Library, further classes are derived from CWnd to provide specific window types. Many of these classes, including CFrameWnd, CMDIFrameWnd, CMDIChildWnd, CView, and CDialog, are designed for further derivation. The control classes derived from CWnd, such as CButton, can be used directly or can be used for further derivation of classes.

Parameters

varChild
Specifies whether the default action to be invoked is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to perform the object's default action) or a child ID (to perform the default action of one of the object's child elements).

varChild
Specifies whether the location to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

Return Value

Returns S_OK on success, a COM error code on failure. See Return Values in IAccessible::accLocation in the Windows SDK.

Remarks

Override this function in your CWnd-derived class if you have nonwindowed user interface elements (other than windowless ActiveX controls, which MFC handles).

For more information, see IAccessible::accLocation in the Windows SDK.

Parameters

lpPaint
Points to the PAINTSTRUCT structure that is to receive painting information.

Return Value

Identifies the device context for CWnd. The pointer may be temporary and should not be stored beyond the scope of EndPaint.

Remarks

The paint structure contains a RECT data structure that has the smallest rectangle that completely encloses the update region and a flag that specifies whether the background has been erased.

The update region is set by the Invalidate, InvalidateRect, or InvalidateRgn member functions and by the system after it sizes, moves, creates, scrolls, or performs any other operation that affects the client area. If the update region is marked for erasing, BeginPaint sends an WM_ONERASEBKGND message.

Do not call the BeginPaint member function except in response to a WM_PAINT message. Each call to the BeginPaint member function must have a matching call to the EndPaint member function. If the caret is in the area to be painted, the BeginPaint member function automatically hides the caret to prevent it from being erased.

Example

// Use BeginPaint and EndPaint when responding to WM_PAINT message// An alternative method is to use CPaintDC in place of // BeginPaint and EndPaintvoid CMdiView::OnPaint()
{
PAINTSTRUCT ps;
CDC* pDC = BeginPaint(&ps);
pDC->Rectangle(CRect(0, 0, 100, 100));
EndPaint(&ps);
// Do not call CView::OnPaint() for painting messages
}

Binds the calling object's default simple bound property (such as an edit control), as marked in the type library, to the underlying cursor that is defined by the DataSource, UserName, Password, and SQL properties of the data-source control.

Remarks

In addition, BringWindowToTop activates pop-up, top-level, and MDI child windows. The BringWindowToTop member function should be used to uncover any window that is partially or completely obscured by any overlapping windows.

Parameters

[in, out] lpClientRect
Pointer to a rectangle structure. On input, this structure contains the client rectangle. After the method is finished, this structure contains the window rectangle that can contain the specified client rectangle.

[in] nAdjustType
Use CWnd::adjustBorder to calculate window coordinates without the WS_EX_CLIENTEDGE style; otherwise, use CWnd::adjustOutside.

Remarks

The size of the calculated window rectangle does not include space for a menu bar.

Example

// Uses CalcWindowRect to determine size for new CFrameWnd// based on the size of the current view. The end result is a// top level frame window of the same size as CMdiView's frame.void CMdiView::OnMyCreateFrame()
{
CFrameWnd* pFrameWnd = new CFrameWnd;
CRect myRect;
GetClientRect(myRect);
pFrameWnd->Create(NULL, _T("My Frame"));
pFrameWnd->CalcWindowRect(&myRect, CWnd::adjustBorder);
pFrameWnd->MoveWindow(0, 0, myRect.Width(), myRect.Height());
pFrameWnd->ShowWindow(SW_SHOW);
}

Remarks

Example

// In this example, tool tips were set up to// pop up when the user moves the mouse// over this edit control.// If the mouse is moved to the upper left-hand// corner, the tool tip would disappear because of// calling CancelToolTips.void CMyEdit::OnMouseMove(UINT nFlags, CPoint point)
{
CRect corner(0, 0, 10, 10);
if (corner.PtInRect(point))
CancelToolTips();
CEdit::OnMouseMove(nFlags, point);
}

Parameters

pAlternateOwner
Pointer to an alternate window relative to which it will be centered (other than the parent window).

Remarks

Usually called from CDialog::OnInitDialog to center dialog boxes relative to the main window of the application. By default, the function centers child windows relative to their parent window, and pop-up windows relative to their owner. If the pop-up window is not owned, it is centered relative to the screen. To center a window relative to a specific window which is not the owner or parent, the pAlternateOwner parameter may be set to a valid window. To force centering relative to the screen, pass the value returned by CWnd::GetDesktopWindow as pAlternateOwner.

Parameters

nIDButton
Specifies the button to be modified.

nCheck
Specifies the action to take. If nCheck is nonzero, the CheckDlgButton member function places a check mark next to the button; if 0, the check mark is removed. For three-state buttons, if nCheck is 2, the button state is indeterminate.

Remarks

The CheckDlgButton function sends a BM_SETCHECK message to the specified button.

Parameters

nflags
Specifies which child windows to skip. This parameter can be a combination of the following values:

Value

Meaning

CWP_ALL

Do not skip any child windows

CWP_SKIPINVISIBLE

Skip invisible child windows

CWP_SKIPDISABLED

Skip disabled child windows

CWP_SKIPTRANSPARENT

Skip transparent child windows

Return Value

Identifies the child window that contains the point. It is NULL if the given point lies outside of the client area. If the point is within the client area but is not contained within any child window, CWnd is returned.

This member function will return a hidden or disabled child window that contains the specified point.

More than one window may contain the given point. However, this function returns only the CWnd* of the first window encountered that contains the point.

The CWnd* that is returned may be temporary and should not be stored for later use.

void ClientToScreen(LPPOINT lpPoint) const; void ClientToScreen(LPRECT lpRect) const; ```
### Parameters
`lpPoint`
Points to a [POINT structure](POINT%20Structure1.md) or `CPoint` object that contains the client coordinates to be converted.
`lpRect`
Points to a [RECT structure](RECT%20Structure1.md) or `CRect` object that contains the client coordinates to be converted.
### Remarks
The `ClientToScreen` member function uses the client coordinates in the **POINT** or `RECT` structure or the `CPoint` or `CRect` object pointed to by `lpPoint` or `lpRect` to compute new screen coordinates; it then replaces the coordinates in the structure with the new coordinates. The new screen coordinates are relative to the upper-left corner of the system display.
The `ClientToScreen` member function assumes that the given point or rectangle is in client coordinates.
### Example
[!CODE [NVC_MFCWindowing#78](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#78)]
## <a name="cwnd__closewindow"></a> CWnd::CloseWindow
Minimizes the window.

### Remarks
This member function emulates the functionality of the function [CloseWindow](http://msdn.microsoft.com/library/windows/desktop/ms632678), as described in the [!INCLUDE[winSDK](../Token/winSDK_md.md)].
## <a name="cwnd__continuemodal"></a> CWnd::ContinueModal
This member function is called by [RunModalLoop](#cwnd__runmodalloop) to determine when the modal state should be exited.

### Return Value
Nonzero if modal loop is to be continued; 0 when [EndModalLoop](#cwnd__endmodalloop) is called.
### Remarks
By default, it returns non-zero until `EndModalLoop` is called.
## <a name="cwnd__create"></a> CWnd::Create
Creates the specified child window and attaches it to the [CWnd](../Topic/CWnd%20Class.md) object.

### Parameters
[in] `lpszClassName`
Pointer to a null-terminated string that contains the name of a registered system window class; or the name of a predefined system window class.
[in] `lpszWindowName`
Pointer to a null-terminated string that contains the window display name; otherwise `NULL` for no window display name.
[in] `dwStyle`
Bitwise combination (OR) of [window styles](../Topic/Window%20Styles.md). The `WS_POPUP` option is not a valid style.
[in] `rect`
The size and location of the window relative to the top-left corner of the parent window.
[in] `pParentWnd`
Pointer to the parent window.
[in] `nID`
ID of the window.
[in] `pContext`
Pointer to a [CCreateContext](../Topic/CCreateContext%20Structure.md) structure that is used to customize the document-view architecture for the application.
### Return Value
`TRUE` if the method was successful; otherwise `FALSE`.
### Remarks
> [!WARNING]
> `CWnd::PreCreateWindow` now assigns the hMenu member of its `CREATESTRUCT` parameter to the `this` pointer if the menu is `NULL` and the style contains `WS_CHILD`. For proper functionality, ensure that your dialog control has an ID that is not `NULL`.
>
> This change fixes a crash in managed/native interop scenarios. A `TRACE` statement in `CWnd::Create` alerts the developer of the problem.
Use the [AfxRegisterWndClass](../Topic/Application%20Information%20and%20Management.md#afxregisterwndclass) function to register window classes. User defined window classes are available in the module where they are registered.
The [CWnd::OnCreate](#cwnd__oncreate) method is called before the `Create` method returns, and before the window becomes visible.
### Example
[!CODE [NVC_MFCWindowing#79](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#79)]
## <a name="cwnd__createaccessibleproxy"></a> CWnd::CreateAccessibleProxy
Creates an Active Accessibility proxy for the specified object.

### Parameters
`wParam`
Identifies the object accessed by the Active Accessibility proxy. Can be one of the following values
|Value|Meaning|
|-----------|-------------|
|**OBJID_CLIENT**|Refers to the window's client area.|
`lParam`
Provides additional message-dependent information.
`pResult`
A pointer to an **LRESULT** that stores the result code.
### Remarks
Creates an Active Accessibility proxy for the specified object.
## <a name="cwnd__createcaret"></a> CWnd::CreateCaret
Creates a new shape for the system caret and claims ownership of the caret.

### Parameters
`pBitmap`
Identifies the bitmap that defines the caret shape.
### Remarks
The bitmap must have previously been created by the [CBitmap::CreateBitmap](../Topic/CBitmap%20Class.md#cbitmap__createbitmap) member function, the [CreateDIBitmap](http://msdn.microsoft.com/library/windows/desktop/dd183491) Windows function, or the [CBitmap::LoadBitmap](../Topic/CBitmap%20Class.md#cbitmap__loadbitmap) member function.
`CreateCaret` automatically destroys the previous caret shape, if any, regardless of which window owns the caret. Once created, the caret is initially hidden. To show the caret, the [ShowCaret](#cwnd__showcaret) member function must be called.
The system caret is a shared resource. `CWnd` should create a caret only when it has the input focus or is active. It should destroy the caret before it loses the input focus or becomes inactive.
### Example
[!CODE [NVC_MFCWindowing#80](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#80)]
## <a name="cwnd__createcontrol"></a> CWnd::CreateControl
Use this member function to create an ActiveX control that will be represented in the MFC program by a `CWnd` object.

### Parameters
*pszClass*
This string may contain the OLE "short name" (ProgID) for the class, e.g., "CIRC3.Circ3Ctrl.1". The name needs to match the same name registered by the control. Alternatively, the string may contain the string form of a **CLSID**, contained in braces, e.g., "{9DBAFCCF-592F-101B-85CE-00608CEC297B}". In either case, `CreateControl` converts the string to the corresponding class ID.
*pszWindowName*
A pointer to the text to be displayed in the control. Sets the value of the control's Caption or Text property (if any). If **NULL**, the control's Caption or Text property is not changed.
`dwStyle`
Windows styles. The available styles are listed under Remarks.
`rect`
Specifies the control's size and position. It can be either a [CRect](../Topic/CRect%20Class.md) object or a [RECT structure](RECT%20Structure1.md).
`ppt`
Points to a [POINT structure](POINT%20Structure1.md) or `CPoint` object that contains the upper left corner of the control.
`pSize`
Points to a [SIZE](http://msdn.microsoft.com/library/windows/desktop/dd145106) structure or `CSize` object that contains the control's size
`pParentWnd`
Specifies the control's parent window. It must not be **NULL**.
`nID`
Specifies the control's ID.
`pPersist`
A pointer to a [CFile](../Topic/CFile%20Class.md) containing the persistent state for the control. The default value is **NULL**, indicating that the control initializes itself without restoring its state from any persistent storage. If not **NULL**, it should be a pointer to a `CFile`-derived object which contains the control's persistent data, in the form of either a stream or a storage. This data could have been saved in a previous activation of the client. The `CFile` can contain other data, but must have its read-write pointer set to the first byte of persistent data at the time of the call to `CreateControl`.
`bStorage`
Indicates whether the data in `pPersist` should be interpreted as IStorage or IStream data. If the data in `pPersist` is a storage, `bStorage` should be **TRUE**. If the data in `pPersist` is a stream, `bStorage` should be **FALSE**. The default value is **FALSE**.
*bstrLicKe*y
Optional license key data. This data is needed only for creating controls that require a run-time license key. If the control supports licensing, you must provide a license key for the creation of the control to succeed. The default value is **NULL**.
`clsid`
The unique class ID of the control.
### Return Value
Nonzero if successful; otherwise 0.
### Remarks
`CreateControl` is a direct analog of the [CWnd::Create](#cwnd__create) function, which creates the window for a `CWnd`. `CreateControl` creates an ActiveX control instead of an ordinary window.
Only a subset of the Windows `dwStyle` flags are supported for `CreateControl`:
- **WS_VISIBLE** Creates a window that is initially visible. Required if you want the control to be visible immediately, like ordinary windows.
- **WS_DISABLED** Creates a window that is initially disabled. A disabled window cannot receive input from the user. Can be set if the control has an Enabled property.
- `WS_BORDER` Creates a window with a thin-line border. Can be set if control has a BorderStyle property.
- **WS_GROUP** Specifies the first control of a group of controls. The user can change the keyboard focus from one control in the group to the next by using the direction keys. All controls defined with the **WS_GROUP** style after the first control belong to the same group. The next control with the **WS_GROUP** style ends the group and starts the next group.
- **WS_TABSTOP** Specifies a control that can receive the keyboard focus when the user presses the TAB key. Pressing the TAB key changes the keyboard focus to the next control of the **WS_TABSTOP** style.
### Example
[!CODE [NVC_MFCWindowing#81](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#81)]
## <a name="cwnd__createex"></a> CWnd::CreateEx
Creates the specified window and attaches it to the `CWnd` object.

### Parameters
`dwExStyle`
Bitwise combination (OR) of [extended window styles](../Topic/Extended%20Window%20Styles.md); otherwise `NULL` for the default extended window style.
`lpszClassName`
Pointer to a null-terminated string that contains the name of a registered system window class; or the name of a predefined system window class.
`lpszWindowName`
Pointer to a null-terminated string that contains the window display name; otherwise `NULL` for no window display name.
`dwStyle`
Bitwise combination (OR) of [window styles](../Topic/Window%20Styles.md); otherwise `NULL` for the default window style.
`x`
The initial horizontal distance of the window from the left side of the screen or the parent window.
`y`
The initial vertical distance of the window from the top of the screen or the parent window.
`nWidth`
The width, in pixels, of the window.
`nHeight`
The height, in pixels, of the window.
`hwndParent`
For a child window, the handle to the parent window; otherwise, the handle of the owner window if the window has an owner.
`nIDorHMenu`
For a child window, the window ID; otherwise, the ID of a menu for the window.
`lpParam`
Pointer to user data that is passed to the [CWnd::OnCreate](#cwnd__oncreate) method in the `lpCreateParams` field.
`rect`
The size and location of the window relative to the screen or the parent window.
`pParentWnd`
For a child window, pointer to the parent window; otherwise, pointer to the owner window if the window has an owner.
`nID`
For a child window, the window ID; otherwise, the ID of a menu for the window.
### Return Value
`TRUE` if the method was successful; otherwise `FALSE`.
### Remarks
> [!WARNING]
> `CWnd::PreCreateWindow` now assigns the hMenu member of its `CREATESTRUCT` parameter to the `this` pointer if the menu is `NULL` and the style contains `WS_CHILD`. For proper functionality, ensure that your dialog control has an ID that is not `NULL`.
>
> This change fixes a crash in managed/native interop scenarios. A `TRACE` statement in `CWnd::Create` alerts the developer of the problem.
The default extended window style is `WS_EX_LEFT`. The default window style is `WS_OVERLAPPED`.
Use the [AfxRegisterWndClass](../Topic/Application%20Information%20and%20Management.md#afxregisterwndclass) function to register window classes. User defined window classes are available in the module where they are registered.
Dimensions for child windows are relative to the top-left corner of the client area of the parent window. Dimensions for top-level windows are relative to the top-left corner of the screen.
The [CWnd::OnCreate](#cwnd__oncreate) method is called before the `CreateEx` method returns, and before the window becomes visible.
### Example
[!CODE [NVC_MFCWindowing#82](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#82)]
## <a name="cwnd__creategraycaret"></a> CWnd::CreateGrayCaret
Creates a gray rectangle for the system caret and claims ownership of the caret.

### Parameters
`nWidth`
Specifies the width of the caret (in logical units). If this parameter is 0, the width is set to the system-defined window-border width.
`nHeight`
Specifies the height of the caret (in logical units). If this parameter is 0, the height is set to the system-defined window-border height.
### Remarks
The caret shape can be a line or a block.
The parameters `nWidth` and `nHeight` specify the caret's width and height (in logical units); the exact width and height (in pixels) depend on the mapping mode.
The system's window-border width or height can be retrieved by the [GetSystemMetrics](http://msdn.microsoft.com/library/windows/desktop/ms724385) Windows function with the **SM_CXBORDER** and **SM_CYBORDER** indexes. Using the window-border width or height ensures that the caret will be visible on a high-resolution display.
The `CreateGrayCaret` member function automatically destroys the previous caret shape, if any, regardless of which window owns the caret. Once created, the caret is initially hidden. To show the caret, the [ShowCaret](#cwnd__showcaret) member function must be called.
The system caret is a shared resource. `CWnd` should create a caret only when it has the input focus or is active. It should destroy the caret before it loses the input focus or becomes inactive.
### Example
[!CODE [NVC_MFCWindowing#83](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#83)]
## <a name="cwnd__createsolidcaret"></a> CWnd::CreateSolidCaret
Creates a solid rectangle for the system caret and claims ownership of the caret.

### Parameters
`nWidth`
Specifies the width of the caret (in logical units). If this parameter is 0, the width is set to the system-defined window-border width.
`nHeight`
Specifies the height of the caret (in logical units). If this parameter is 0, the height is set to the system-defined window-border height.
### Remarks
The caret shape can be a line or block.
The parameters `nWidth` and `nHeight` specify the caret's width and height (in logical units); the exact width and height (in pixels) depend on the mapping mode.
The system's window-border width or height can be retrieved by the [GetSystemMetrics](http://msdn.microsoft.com/library/windows/desktop/ms724385) Windows function with the **SM_CXBORDER** and **SM_CYBORDER** indexes. Using the window-border width or height ensures that the caret will be visible on a high-resolution display.
The `CreateSolidCaret` member function automatically destroys the previous caret shape, if any, regardless of which window owns the caret. Once created, the caret is initially hidden. To show the caret, the [ShowCaret](#cwnd__showcaret) member function must be called.
The system caret is a shared resource. `CWnd` should create a caret only when it has the input focus or is active. It should destroy the caret before it loses the input focus or becomes inactive.
### Example
[!CODE [NVC_MFCWindowing#84](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#84)]
## <a name="cwnd__cwnd"></a> CWnd::CWnd
Constructs a `CWnd` object.

### Remarks
The Windows window is not created and attached until the [CreateEx](#cwnd__createex) or [Create](#cwnd__create) member function is called.
## <a name="cwnd__default"></a> CWnd::Default
Calls the default window procedure.

### Return Value
Depends on the message sent.
### Remarks
The default window procedure provides default processing for any window message that an application does not process. This member function ensures that every message is processed.
### Example
[!CODE [NVC_MFCWindowing#85](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#85)]
## <a name="cwnd__defwindowproc"></a> CWnd::DefWindowProc
Calls the default window procedure, which provides default processing for any window message that an application does not process.

### Parameters
`message`
Specifies the Windows message to be processed.
`wParam`
Specifies additional message-dependent information.
`lParam`
Specifies additional message-dependent information.
### Return Value
Depends on the message sent.
### Remarks
This member function ensures that every message is processed. It should be called with the same parameters as those received by the window procedure.
## <a name="cwnd__deletetempmap"></a> CWnd::DeleteTempMap
Called automatically by the idle time handler of the `CWinApp` object.

### Return Value
Nonzero if the window is destroyed; otherwise 0.
### Remarks
The `DestroyWindow` member function sends appropriate messages to the window to deactivate it and remove the input focus. It also destroys the window's menu, flushes the application queue, destroys outstanding timers, removes Clipboard ownership, and breaks the Clipboard-viewer chain if `CWnd` is at the top of the viewer chain. It sends [WM_DESTROY](#cwnd__ondestroy) and [WM_NCDESTROY](#cwnd__onncdestroy) messages to the window. It does not destroy the `CWnd` object.
`DestroyWindow` is a place holder for performing cleanup. Because `DestroyWindow` is a virtual function, it is shown in any `CWnd`-derived class in Class View. But even if you override this function in your `CWnd`-derived class, `DestroyWindow` is not necessarily called. If `DestroyWindow` is not called in the MFC code, then you have to explicitly call it in your own code if you want it to be called.
Assume, for example, you have overridden `DestroyWindow` in a `CView`-derived class. Since MFC source code does not call `DestroyWindow` in any of its `CFrameWnd`-derived classes, your overridden `DestroyWindow` will not be called unless you call it explicitly.
If the window is the parent of any windows, these child windows are automatically destroyed when the parent window is destroyed. The `DestroyWindow` member function destroys child windows first and then the window itself.
The `DestroyWindow` member function also destroys modeless dialog boxes created by [CDialog::Create](../Topic/CDialog%20Class.md#cdialog__create).
If the `CWnd` being destroyed is a child window and does not have the [WS_EX_NOPARENTNOTIFY](../Topic/Extended%20Window%20Styles.md) style set, then the [WM_PARENTNOTIFY ](https://msdn.microsoft.com/library/ms632638.aspx) message is sent to the parent.
### Example
[!CODE [NVC_MFCWindowing#87](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#87)]
## <a name="cwnd__detach"></a> CWnd::Detach
Detaches a Windows handle from a `CWnd` object and returns the handle.

### Return Value
A `HWND` to the Windows object.
### Example
See the example for [CWnd::Attach](#cwnd__attach).
## <a name="cwnd__dlgdirlist"></a> CWnd::DlgDirList
Fills a list box with a file or directory listing.

### Parameters
`lpPathSpec`
Points to a null-terminated string that contains the path or filename. `DlgDirList` modifies this string, which should be long enough to contain the modifications. For more information, see the following "Remarks" section.
`nIDListBox`
Specifies the identifier of a list box. If `nIDListBox` is 0, `DlgDirList` assumes that no list box exists and does not attempt to fill one.
`nIDStaticPath`
Specifies the identifier of the static-text control used to display the current drive and directory. If `nIDStaticPath` is 0, `DlgDirList` assumes that no such text control is present.
`nFileType`
Specifies the attributes of the files to be displayed. It can be any combination of the following values:
- **DDL_READWRITE** Read-write data files with no additional attributes.
- **DDL_READONLY** Read-only files.
- **DDL_HIDDEN** Hidden files.
- **DDL_SYSTEM** System files.
- **DDL_DIRECTORY** Directories.
- **DDL_ARCHIVE** Archives.
- **DDL_POSTMSGS LB_DIR** flag. If the **LB_DIR** flag is set, Windows places the messages generated by `DlgDirList` in the application's queue; otherwise, they are sent directly to the dialog-box procedure.
- **DDL_DRIVES** Drives. If the **DDL_DRIVES** flag is set, the **DDL_EXCLUSIVE** flag is set automatically. Therefore, to create a directory listing that includes drives and files, you must call `DlgDirList` twice: once with the **DDL_DRIVES** flag set and once with the flags for the rest of the list.
- **DDL_EXCLUSIVE** Exclusive bit. If the exclusive bit is set, only files of the specified type are listed; otherwise normal files and files of the specified type are listed.
### Return Value
Nonzero if the function is successful; otherwise 0.
### Remarks
`DlgDirList` sends [LB_RESETCONTENT](http://msdn.microsoft.com/library/windows/desktop/bb761325) and [LB_DIR](http://msdn.microsoft.com/library/windows/desktop/bb775185) messages to the list box. It fills the list box specified by `nIDListBox` with the names of all files that match the path given by `lpPathSpec`.
The `lpPathSpec` parameter has the following form:
`[drive:] [ [\u]directory[\idirectory]...\u] [filename]`
In this example, `drive` is a drive letter, `directory` is a valid directory name, and *filename* is a valid filename that must contain at least one wildcard. The wildcards are a question mark ( ****), which means match any character, and an asterisk ( **\***), meaning match any number of characters.
If you specify a 0-length string for `lpPathSpec`, or if you specify only a directory name but do not include any file specification, the string will be changed to "*.\*".
If `lpPathSpec` includes a drive and/or directory name, the current drive and directory are changed to the designated drive and directory before the list box is filled. The text control identified by `nIDStaticPath` is also updated with the new drive and/or directory name.
After the list box is filled, `lpPathSpec` is updated by removing the drive and/or directory portion of the path.
### Example
[!CODE [NVC_MFCWindowing#88](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#88)]
## <a name="cwnd__dlgdirlistcombobox"></a> CWnd::DlgDirListComboBox
Fills the list box of a combo box with a file or directory listing.

### Parameters
`lpPathSpec`
Points to a null-terminated string that contains the path or filename. `DlgDirListComboBox` modifies this string, so this data should not be in the form of a string literal. See the following "Remarks" section.
`nIDComboBox`
Specifies the identifier of a combo box in a dialog box. If `nIDComboBox` is 0, `DlgDirListComboBox` assumes that no combo box exists and does not attempt to fill one.
`nIDStaticPath`
Specifies the identifier of the static-text control used to display the current drive and directory. If `nIDStaticPath` is 0, `DlgDirListComboBox` assumes that no such text control is present.
`nFileType`
Specifies DOS file attributes of the files to be displayed. It can be any combination of the following values:
- **DDL_READWRITE** Read-write data files with no additional attributes.
- **DDL_READONLY** Read-only files.
- **DDL_HIDDEN** Hidden files.
- **DDL_SYSTEM** System files.
- **DDL_DIRECTORY** Directories.
- **DDL_ARCHIVE** Archives.
- **DDL_POSTMSGS CB_DIR** flag. If the **CB_DIR** flag is set, Windows places the messages generated by `DlgDirListComboBox` in the application's queue; otherwise, they are sent directly to the dialog-box procedure.
- **DDL_DRIVES** Drives. If the **DDL_DRIVES** flag is set, the **DDL_EXCLUSIVE** flag is set automatically. Therefore, to create a directory listing that includes drives and files, you must call `DlgDirListComboBox` twice: once with the **DDL_DRIVES** flag set and once with the flags for the rest of the list.
- **DDL_EXCLUSIVE** Exclusive bit. If the exclusive bit is set, only files of the specified type are listed; otherwise normal files and files of the specified type are listed.
### Return Value
Specifies the outcome of the function. It is nonzero if a listing was made, even an empty listing. A 0 return value implies that the input string did not contain a valid search path.
### Remarks
`DlgDirListComboBox` sends [CB_RESETCONTENT](http://msdn.microsoft.com/library/windows/desktop/bb775878) and [CB_DIR](http://msdn.microsoft.com/library/windows/desktop/bb775832) messages to the combo box. It fills the list box of the combo box specified by `nIDComboBox` with the names of all files that match the path given by `lpPathSpec`.
The `lpPathSpec` parameter has the following form:
`[drive:] [ [\u]directory[\idirectory]...\u] [filename]`
In this example, `drive` is a drive letter, `directory` is a valid directory name, and *filename* is a valid filename that must contain at least one wildcard. The wildcards are a question mark ( ****), which means match any character, and an asterisk ( **\***), which means match any number of characters.
If you specify a zero-length string for `lpPathSpec`, the current directory will be used and `lpPathSpec` will not be modified. If you specify only a directory name but do not include any file specification, the string will be changed to "*".
If `lpPathSpec` includes a drive and/or directory name, the current drive and directory are changed to the designated drive and directory before the list box is filled. The text control identified by `nIDStaticPath` is also updated with the new drive and/or directory name.
After the combo-box list box is filled, `lpPathSpec` is updated by removing the drive and/or directory portion of the path.
### Example
[!CODE [NVC_MFCWindowing#89](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#89)]
## <a name="cwnd__dlgdirselect"></a> CWnd::DlgDirSelect
Retrieves the current selection from a list box.

### Parameters
`lpString`
Points to a buffer that is to receive the current selection in the list box.
`nIDListBox`
Specifies the integer ID of a list box in the dialog box.
### Return Value
Nonzero if successful; otherwise 0.
### Remarks
It assumes that the list box has been filled by the [DlgDirList](#cwnd__dlgdirlist) member function and that the selection is a drive letter, a file, or a directory name.
The `DlgDirSelect` member function copies the selection to the buffer given by `lpString`. If there is no selection, `lpString` does not change.
`DlgDirSelect` sends [LB_GETCURSEL](http://msdn.microsoft.com/library/windows/desktop/bb775197) and [LB_GETTEXT](http://msdn.microsoft.com/library/windows/desktop/bb761313) messages to the list box.
It does not allow more than one filename to be returned from a list box. The list box must not be a multiple-selection list box.
## <a name="cwnd__dlgdirselectcombobox"></a> CWnd::DlgDirSelectComboBox
Retrieves the current selection from the list box of a combo box.

### Parameters
`lpString`
Points to a buffer that is to receive the selected path.
`nIDComboBox`
Specifies the integer ID of the combo box in the dialog box.
### Return Value
Nonzero if successful; otherwise 0.
### Remarks
It assumes that the list box has been filled by the [DlgDirListComboBox](#cwnd__dlgdirlistcombobox) member function and that the selection is a drive letter, a file, or a directory name.
The `DlgDirSelectComboBox` member function copies the selection to the specified buffer. If there is no selection, the contents of the buffer are not changed.
`DlgDirSelectComboBox` sends [CB_GETCURSEL](http://msdn.microsoft.com/library/windows/desktop/bb775845) and [CB_GETLBTEXT](http://msdn.microsoft.com/library/windows/desktop/bb775862) messages to the combo box.
It does not allow more than one filename to be returned from a combo box.
## <a name="cwnd__dodataexchange"></a> CWnd::DoDataExchange
Called by the framework to exchange and validate dialog data.

### Parameters
`pDX`
A pointer to a `CDataExchange` object.
### Remarks
Never call this function directly. It is called by the [UpdateData](#cwnd__updatedata) member function. Call `UpdateData` to initialize a dialog box's controls or retrieve data from a dialog box.
When you derive an application-specific dialog class from [CDialog](../Topic/CDialog%20Class.md), you need to override this member function if you wish to utilize the framework's automatic data exchange and validation. The Add Variable wizard will write an overridden version of this member function for you containing the desired "data map" of dialog data exchange (DDX) and validation (DDV) global function calls.
To automatically generate an overridden version of this member function, first create a dialog resource with the dialog editor, then derive an application-specific dialog class. Then use the Add Variable wizard to associate variables, data, and validation ranges with various controls in the new dialog box. The wizard then writes the overridden `DoDataExchange`, which contains a data map. The following is an example DDX/DDV code block generated by the Add Variable wizard:
[!CODE [NVC_MFCWindowing#90](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#90)]
The `DoDataExchange` overridden member function must precede the macro statements in your source file.
For more information on dialog data exchange and validation, see [Displaying and Manipulating Data in a Form](../Topic/Displaying%20and%20Manipulating%20Data%20in%20a%20Form.md) and [Dialog Data Exchange and Validation](../Topic/Dialog%20Data%20Exchange%20and%20Validation.md). For a description of the DDX_ and DDV_ macros generated by the Add Variable wizard, see [Technical Note 26](../Topic/TN026:%20DDX%20and%20DDV%20Routines.md).
## <a name="cwnd__dragacceptfiles"></a> CWnd::DragAcceptFiles
Call this member function from within a window, using a `CWnd` pointer, in your application's [CWinApp::InitInstance](../Topic/CWinApp%20Class.md#cwinapp__initinstance) function to indicate that the window accepts dropped files from the Windows File Manager or File Explorer.

### Parameters
*BAccept*
Flag that indicates whether dragged files are accepted.
### Remarks
Only the window that calls `DragAcceptFiles` with the `bAccept` parameter set to **TRUE** has identified itself as able to process the Windows message `WM_DROPFILES`. For example, in an MDI application, if the `CMDIFrameWnd` window pointer is used in the `DragAcceptFiles` function call, only the `CMDIFrameWnd` window gets the `WM_DROPFILES` message. This message is not sent to all open `CMDIChildWnd` windows. For a `CMDIChildWnd` window to receive this message, you must call `DragAcceptFiles` with the `CMDIChildWnd` window pointer.
To discontinue receiving dragged files, call the member function with `bAccept` set to **FALSE**.
## <a name="cwnd__dragdetect"></a> CWnd::DragDetect
Captures the mouse and tracks its movement until the user releases the left button, presses the ESC key, or moves the mouse outside the drag rectangle around the specified point.

### Parameters
`pt`
Initial position of the mouse, in screen coordinates. The function determines the coordinates of the drag rectangle by using this point.
### Return Value
If the user moved the mouse outside of the drag rectangle while holding down the left button , the return value is nonzero.
If the user did not move the mouse outside of the drag rectangle while holding down the left button , the return value is zero.
### Remarks
This member function emulates the functionality of the function [DragDetect](http://msdn.microsoft.com/library/windows/desktop/ms646256), as described in the [!INCLUDE[winSDK](../Token/winSDK_md.md)].
## <a name="cwnd__drawanimatedrects"></a> CWnd::DrawAnimatedRects
Draws a wire-frame rectangle and animates it to indicate the opening of an icon or the minimizing or maximizing of a window.

### Parameters
*idAni*
Specifies the type of animation. If you specify **IDANI_CAPTION**, the window caption will animate from the position specified by `lprcFrom` to the position specified by `lprcTo`. The effect is similar to minimizing or maximizing a window.
`lprcFrom`
Pointer to a [RECT](http://msdn.microsoft.com/library/windows/desktop/dd162897) structure specifying the location and size of the icon or minimized window.
`lprcTo`
Pointer to a [RECT](http://msdn.microsoft.com/library/windows/desktop/dd162897) structure specifying the location and size of the restored window
### Return Value
Nonzero if the function succeeds; otherwise 0.
### Remarks
This member function emulates the functionality of the function [DrawAnimatedRects](http://msdn.microsoft.com/library/windows/desktop/dd162475), as described in the [!INCLUDE[winSDK](../Token/winSDK_md.md)].
## <a name="cwnd__drawcaption"></a> CWnd::DrawCaption
Draws a window caption.

### Parameters
`pDC`
A pointer to a device context. The function draws the window caption into this device context.
`lprc`
A pointer to a RECT structure that specifies the bounding rectangle for the window caption.
`uFlags`
Specifies drawing options. For a complete list of values, see [DrawCaption](http://msdn.microsoft.com/library/windows/desktop/dd162476).
### Return Value
Nonzero if the function succeeds; otherwise 0.
### Remarks
This member function emulates the functionality of the function [DrawCaption](http://msdn.microsoft.com/library/windows/desktop/dd162476), as described in the [!INCLUDE[winSDK](../Token/winSDK_md.md)].
## <a name="cwnd__drawmenubar"></a> CWnd::DrawMenuBar
Redraws the menu bar.

### Remarks
If a menu bar is changed after Windows has created the window, call this function to draw the changed menu bar.
### Example
See the example for [CWnd::GetMenu](#cwnd__getmenu).
## <a name="cwnd__enableactiveaccessibility"></a> CWnd::EnableActiveAccessibility
Enables user-defined Active Accessibility functions.

### Remarks
MFC's default Active Accessibility support is sufficient for standard windows and controls, including ActiveX controls; however, if your `CWnd`-derived class contains nonwindowed user interface elements, MFC has no way of knowing about them. In that case, you must override the appropriate [Active Accessibility member functions](assetId:///68af04ac-4eb9-4b7d-b33f-c45512097a74) in your class, and you must call **EnableActiveAccessibility** in the class's constructor.
## <a name="cwnd__enabledynamiclayout"></a> CWnd::EnableDynamicLayout
Enables or disables the dynamic layout manager. When dynamic layout is enabled, the position and size of child windows can adjust dynamically when the user resizes the window.

### Parameters
`bEnable`
TRUE to enable dynamic layout; FALSE to disable dynamic layout.
### Remarks
If you want to enable dynamic layout, you have to do more than just call this method. You also have to provide dynamic layout information which species how the controls in the window respond to size changes. You can specify this information in the resource editor, or programmatically, for each control. See [Dynamic Layout](../Topic/Dynamic%20Layout.md).
## <a name="cwnd__enabled2dsupport"></a> CWnd::EnableD2DSupport
Enables or disables window D2D support. Call this method before the main window is initialized.

### Parameters
`bEnable`
Specifies whether to turn on, or off D2D support.
`bUseDCRenderTarget`
Species whether to use the Device Context (DC) render target, CDCRenderTarget. If FALSE, CHwndRenderTarget is used.
## <a name="cwnd__enablescrollbar"></a> CWnd::EnableScrollBar
Enables or disables one or both arrows of a scroll bar.

### Parameters
*nSBFlags*
Specifies the scroll-bar type. Can have one of the following values:
- **SB_BOTH** Enables or disables the arrows of the horizontal and vertical scroll bars associated with the window.
- **SB_HORZ** Enables or disables the arrows of the horizontal scroll bar associated with the window.
- **SB_VERT** Enables or disables the arrows of the vertical scroll bar associated with the window.
`nArrowFlags`
Specifies whether the scroll-bar arrows are enabled or disabled and which arrows are enabled or disabled. Can have one of the following values:
- **ESB_ENABLE_BOTH** Enables both arrows of a scroll bar (default).
- **ESB_DISABLE_LTUP** Disables the left arrow of a horizontal scroll bar or the up arrow of a vertical scroll bar.
- **ESB_DISABLE_RTDN** Disables the right arrow of a horizontal scroll bar or the down arrow of a vertical scroll bar.
- **ESB_DISABLE_BOTH** Disables both arrows of a scroll bar.
### Return Value
Nonzero if the arrows are enabled or disabled as specified. Otherwise it is 0, which indicates that the arrows are already in the requested state or that an error occurred.
## <a name="cwnd__enablescrollbarctrl"></a> CWnd::EnableScrollBarCtrl
Enables or disables the scroll bar for this window.

### Parameters
`nBar`
The scroll-bar identifier.
`bEnable`
Specifies whether the scroll bar is to be enabled or disabled.
### Remarks
If the window has a sibling scroll-bar control, that scroll bar is used; otherwise the window's own scroll bar is used.
## <a name="cwnd__enabletooltips"></a> CWnd::EnableToolTips
Enables tool tips for the given window.

### Parameters
`bEnable`
Specifies whether the tool tip control is enabled or disabled. **TRUE** enables the control; **FALSE** disables the control.
### Return Value
**TRUE** if tool tips are enabled; otherwise **FALSE**.
### Remarks
Override [OnToolHitTest](#cwnd__ontoolhittest) to provide the [TOOLINFO](http://msdn.microsoft.com/library/windows/desktop/bb760256) struct or structs for the window.
> [!NOTE]
> Some windows, such as [CToolBar](../Topic/CToolBar%20Class.md), provide a built-in implementation of [OnToolHitTest](#cwnd__ontoolhittest).
See [TOOLINFO](http://msdn.microsoft.com/library/windows/desktop/bb760256) in the [!INCLUDE[winSDK](../Token/winSDK_md.md)] for more information on this structure.
Simply calling `EnableToolTips` is not enough to display tool tips for your child controls unless the parent window is derived from `CFrameWnd`. This is because `CFrameWnd` provides a default handler for the **TTN_NEEDTEXT** notification. If your parent window is not derived from `CFrameWnd`, that is, if it is a dialog box or a form view, tool tips for your child controls will not display correctly unless you provide a handler for the **TTN_NEEDTEXT** tool tip notification. See [Tool Tips](../Topic/Tool%20Tips%20in%20Windows%20Not%20Derived%20from%20CFrameWnd.md).
The default tool tips provided for your windows by `EnableToolTips` do not have text associated with them. To retrieve text for the tool tip to display, the **TTN_NEEDTEXT** notification is sent to the tool tip control's parent window just before the tool tip window is displayed. If there is no handler for this message to assign some value to the `pszText` member of the **TOOLTIPTEXT** structure, there will be no text displayed for the tool tip.
### Example
[!CODE [NVC_MFCWindowing#91](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#91)]
[!CODE [NVC_MFCWindowing#92](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#92)]
## <a name="cwnd__enabletrackingtooltips"></a> CWnd::EnableTrackingToolTips
Enables or disables tracking tooltips.

### Parameters
`bEnable`
Specifies whether tracking tool tips are enabled or disabled. If this parameter is **TRUE**, the tracking tool tips will be enabled. If this parameter is **FALSE**, the tracking tool tips will be disabled.
### Return Value
Indicates the state before the `EnableWindow` member function was called. The return value is nonzero if the window was previously disabled. The return value is 0 if the window was previously enabled or an error occurred.
### Remarks
Tracking tool tips are tool tip windows that you can dynamically position on the screen. By rapidly updating the position, the tool tip window appears to move smoothly, or "track." This functionality can be useful if you need tool tip text to follow the position of the pointer as it moves.
## <a name="cwnd__enablewindow"></a> CWnd::EnableWindow
Enables or disables mouse and keyboard input.

### Parameters
`bEnable`
Specifies whether the given window is to be enabled or disabled. If this parameter is **TRUE**, the window will be enabled. If this parameter is **FALSE**, the window will be disabled.
### Return Value
Indicates the state before the `EnableWindow` member function was called. The return value is nonzero if the window was previously disabled. The return value is 0 if the window was previously enabled or an error occurred.
### Remarks
When input is disabled, input such as mouse clicks and keystrokes is ignored. When input is enabled, the window processes all input.
If the enabled state is changing, the [WM_ENABLE](#cwnd__onenable) message is sent before this function returns.
If disabled, all child windows are implicitly disabled, although they are not sent `WM_ENABLE` messages.
A window must be enabled before it can be activated. For example, if an application is displaying a modeless dialog box and has disabled its main window, the main window must be enabled before the dialog box is destroyed. Otherwise, another window will get the input focus and be activated. If a child window is disabled, it is ignored when Windows tries to determine which window should get mouse messages.
By default, a window is enabled when it is created. An application can specify the **WS_DISABLED** style in the [Create](#cwnd__create) or [CreateEx](#cwnd__createex) member function to create a window that is initially disabled. After a window has been created, an application can also use the `EnableWindow` member function to enable or disable the window.
An application can use this function to enable or disable a control in a dialog box. A disabled control cannot receive the input focus, nor can a user access it.
### Example
[!CODE [NVC_MFCWindowing#93](../CodeSnippet/VS_Snippets_Cpp/NVC_MFCWindowing#93)]
## <a name="cwnd__endmodalloop"></a> CWnd::EndModalLoop
Terminates a call to `RunModalLoop`.

### Parameters
`nResult`
Contains the value to be returned to the caller of [RunModalLoop](#cwnd__runmodalloop).
### Remarks
The `nResult` parameter is propagated to the return value from `RunModalLoop`.
## <a name="cwnd__endmodalstate"></a> CWnd::EndModalState
Call this member function to change a frame window from modal to modeless.

### Parameters
`lpPaint`
Points to a [PAINTSTRUCT](../Topic/PAINTSTRUCT%20Structure.md) structure that contains the painting information retrieved by the [BeginPaint](#cwnd__beginpaint) member function.
### Remarks
The `EndPaint` member function is required for each call to the `BeginPaint` member function, but only after painting is complete.
If the caret was hidden by the `BeginPaint` member function, `EndPaint` restores the caret to the screen.
### Example
See the example for [CWnd::BeginPaint](#cwnd__beginpaint).
## <a name="cwnd__executedlginit"></a> CWnd::ExecuteDlgInit
Initiates a dialog resource.

Parameters

lpszResourceName
A pointer to a null-terminated string specifying the name of the resource.

lpResource
A pointer to a resource.

Return Value

TRUE if a dialog resource is executed; otherwise FALSE.

Remarks

ExecuteDlgInit will use resources bound to the executing module, or resources from other sources. To accomplish this, ExecuteDlgInit finds a resource handle by calling AfxFindResourceHandle. If your MFC application does not use the shared DLL (MFCx0[U][D].DLL), AfxFindResourceHandle calls AfxGetResourceHandle, which returns the current resource handle for the executable. If your MFC application that uses MFCx0[U][D].DLL, AfxFindResourceHandle traverses the CDynLinkLibrary object list of shared and extension DLLs looking for the correct resource handle.

Parameters

pMsg
A pointer to the tool tip message.

Remarks

In most MFC applications this method is called by the framework from PreTranslateMessage and EnableToolTips, and you do not need to call it yourself.

However, in certain applications, for example some ActiveX controls, these methods might not be invoked by the framework, and you will need to call FilterToolTipMessage yourself. For more information, see Methods of Creating Tool Tips.

Remarks

Example

// activate an application with a window with a specific class name
BOOL CMyApp::FirstInstance()
{
CWnd *pWndPrev, *pWndChild;
// Determine if a window with the class name exists...
pWndPrev = CWnd::FindWindow(_T("MyNewClass"), NULL);
if (NULL != pWndPrev)
{
// If so, does it have any popups?
pWndChild = pWndPrev->GetLastActivePopup();
// If iconic, restore the main windowif (pWndPrev->IsIconic())
pWndPrev->ShowWindow(SW_RESTORE);
// Bring the main window or its popup to the foreground
pWndChild->SetForegroundWindow();
// and you are done activating the other applicationreturn FALSE;
}
return TRUE;
}

Remarks

Parameters

bInvert
Specifies whether the CWnd is to be flashed or returned to its original state. The CWnd is flashed from one state to the other if bInvert is TRUE. If bInvert is FALSE, the window is returned to its original state (either active or inactive).

Return Value

Nonzero if the window was active before the call to the FlashWindow member function; otherwise 0.

Remarks

For successive flashing, create a system timer and repeatedly call FlashWindow. Flashing the CWnd means changing the appearance of its title bar as if the CWnd were changing from inactive to active status, or vice versa. (An inactive title bar changes to an active title bar; an active title bar changes to an inactive title bar.)

Typically, a window is flashed to inform the user that it requires attention but that it does not currently have the input focus.

The bInvert parameter should be FALSE only when the window is getting the input focus and will no longer be flashing; it should be TRUE on successive calls while waiting to get the input focus.

This function always returns nonzero for minimized windows. If the window is minimized, FlashWindow will simply flash the window's icon; bInvert is ignored for minimized windows.

Parameters

dwFlags
Specifies the flash status. For a complete list of values, see the FLASHWINFO structure.

uCount
Specifies the number of times to flash the window.

dwTimeout
Specifies the rate, in milliseconds, at which the window will be flashed. If dwTimeout is zero, the function uses the default cursor blink rate.

Return Value

The return value specifies the window's state before the call to the FlashWindowEx function. If the window caption was drawn as active before the call, the return value is nonzero. Otherwise, the return value is zero.

Remarks

This method emulates the functionality of the function FlashWindowEx, as described in the Windows SDK.

Return Value

Remarks

Override this function in your CWnd-derived class if you have nonwindowed user interface elements (other than windowless ActiveX controls, which MFC handles). Call the base class version and then add the nonwindowed child elements.

Parameters

varChild
Specifies whether the default action to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

pszDefaultAction
Address of a BSTR that receives a localized string describing the default action for the specified object, or NULL if this object has no default action.

Parameters

varChild
Specifies whether the description to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

pszDescription
Address of a BSTR that receives a localized string describing the specified object, or NULL if no description is available for this object.

Parameters

varChild
Specifies whether the help information to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

pszHelp
Address of a BSTR that receives the localized string containing the help information for the specified object, or NULL if no help information is available.

Parameters

pszHelpFile
Address of a BSTR that receives the full path of the WinHelp file associated with the specified object, if any.

varChild
Specifies whether the Help topic to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain a Help topic for the object) or a child ID (to obtain a Help topic for one of the object's child elements).

Parameters

varChild
Specifies whether the keyboard shortcut to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

pszKeyboardShortcut
Address of a BSTR that receives a localized string identifying the keyboard shortcut, or NULL if no keyboard shortcut is associated with the specified object.

Parameters

varChild
Specifies whether the name to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

pszName
Address of a BSTR that receives a string containing the specified object's name.

Parameters

varChild
Specifies whether the role information to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

Parameters

varChild
Specifies whether the state information to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

Parameters

varChild
Specifies whether the value information to be retrieved is that of the object or one of the object's child elements. This parameter can be either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element).

pszValue
Address of the BSTR that receives a localized string containing the object's current value.

Return Value

Identifies the window that has the mouse capture. It is NULL if no window has the mouse capture.

The return value may be temporary and should not be stored for later use.

Remarks

Only one window has the mouse capture at any given time. A window receives the mouse capture when the SetCapture member function is called. This window receives mouse input whether or not the cursor is within its borders.

Parameters

lpRect
Points to a RECT structure or a CRect object to receive the client coordinates. The left and top members will be 0. The right and bottom members will contain the width and height of the window.

Remarks

The client coordinates specify the upper-left and lower-right corners of the client area. Since client coordinates are relative to the upper-left corners of the CWnd client area, the coordinates of the upper-left corner are (0,0).

Example

// The following code fragment is taken from CMyDlg::OnInitDialog// CMyDlg is a CDialog-derived class.// IDC_MSACALCTRL1 is the ID of the Calendar control OCX embedded // on this dialog
CWnd *pWndCal = GetDlgItem(IDC_MSACALCTRL1);
// Use the IUnknown of the control
LPUNKNOWN pUnk = pWndCal->GetControlUnknown();
// From there get the IDispatch interface of control
LPDISPATCH pDisp = NULL;
pUnk->QueryInterface(IID_IDispatch, (LPVOID*)&pDisp);
// use IDispatch method to invoke the control's functionality

Return Value

Identifies the device context for the CWnd client area if successful; otherwise, the return value is NULL. The pointer may be temporary and should not be stored for later use.

Remarks

For common device contexts, GetDC assigns default attributes to the context each time it is retrieved. For class and private contexts, GetDC leaves the previously assigned attributes unchanged. The device context can be used in subsequent graphics device interface (GDI) functions to draw in the client area.

Unless the device context belongs to a window class, the ReleaseDC member function must be called to release the context after painting.

A device context belonging to the CWnd class is returned by the GetDC member function if CS_CLASSDC, CS_OWNDC, or CS_PARENTDC was specified as a style in the WNDCLASS structure when the class was registered.

Parameters

prgnClip
Identifies a clipping region that may be combined with the visible region of the client window.

flags
Can have one of the following preset values:

DCX_CACHE Returns a device context from the cache rather than the OWNDC or CLASSDC window. Overrides CS_OWNDC and CS_CLASSDC.

DCX_CLIPCHILDREN Excludes the visible regions of all child windows below the CWnd window.

DCX_CLIPSIBLINGS Excludes the visible regions of all sibling windows above the CWnd window.

DCX_EXCLUDERGN Excludes the clipping region identified by prgnClip from the visible region of the returned device context.

DCX_INTERSECTRGN Intersects the clipping region identified by prgnClip within the visible region of the returned device context.

DCX_LOCKWINDOWUPDATE Allows drawing even if there is a LockWindowUpdate call in effect that would otherwise exclude this window. This value is used for drawing during tracking.

DCX_PARENTCLIP Uses the visible region of the parent window and ignores the parent window's WS_CLIPCHILDREN and WS_PARENTDC style bits. This value sets the device context's origin to the upper-left corner of the CWnd window.

DCX_WINDOW Returns a device context that corresponds to the window rectangle rather than the client rectangle.

Return Value

The device context for the specified window if the function is successful; otherwise NULL.

Remarks

The device context can be used in subsequent GDI functions to draw in the client area.

This function, which is an extension to the GetDC function, gives an application more control over how and whether a device context for a window is clipped.

Unless the device context belongs to a window class, the ReleaseDC function must be called to release the context after drawing. Since only five common device contexts are available at any given time, failure to release a device context can prevent other applications from gaining access to a device context.

To obtain a cached device context, an application must specify DCX_CACHE. If DCX_CACHE is not specified and the window is neither CS_OWNDC nor CS_CLASSDC, this function returns NULL.

A device context with special characteristics is returned by the GetDCEx function if the CS_CLASSDC, CS_OWNDC, or CS_PARENTDC style was specified in the WNDCLASS structure when the class was registered.

For more information about these characteristics, see the description of the WNDCLASS structure in the Windows SDK.

Remarks

Parameters

nID
Specifies the identifier of the control or child window to be retrieved.

bOnlyPerm
Specifies whether the window to be returned can be temporary. If TRUE, only a permanent window can be returned; if FALSE, the function can return a temporary window. For more information on temporary windows see Technical Note 3.

Return Value

A pointer to a CWnd object, or NULL if no child window is found.

Remarks

This member function searches the entire tree of child windows, not only the windows that are immediate children.

Parameters

nID
Specifies the integer identifier of the dialog-box control to be translated.

lpTrans
Points to the Boolean variable that is to receive the translated flag.

bSigned
Specifies whether the value to be retrieved is signed.

Return Value

Specifies the translated value of the dialog-box item text. Since 0 is a valid return value, lpTrans must be used to detect errors. If a signed return value is desired, cast it as an int type.

The function returns 0 if the translated number is greater than INT_MAX (for signed numbers) or UINT_MAX (for unsigned).

When errors occur, such as encountering nonnumeric characters and exceeding the above maximum, GetDlgItemInt copies 0 to the location pointed to by lpTrans. If there are no errors, lpTrans receives a nonzero value. If lpTrans is NULL, GetDlgItemInt does not warn about errors.

Remarks

It translates the text of the specified control in the given dialog box into an integer value by stripping any extra spaces at the beginning of the text and converting decimal digits. It stops the translation when it reaches the end of the text or encounters any nonnumeric character.

If bSigned is TRUE, GetDlgItemInt checks for a minus sign (–) at the beginning of the text and translates the text into a signed number. Otherwise, it creates an unsigned value.

Return Value

A pointer to a cursor that is defined by a data-source control. MFC takes care of calling AddRef for the pointer.

Remarks

Use the returned pointer to set the ICursor property of a complex data-bound control, such as the data-bound grid control. A data-source control will not become active until the first bound control requests its cursor. This can happen either explicitly by a call to GetDSCCursor or implicitly by the MFC binding manager. In either case, you can force a data-source control to become active by calling GetDSCCursor and then calling Release on the returned pointer to IUnknown. Activation will cause the data-source control to attempt to connect to the underlying data source. The returned pointer might be used in the following context:

Return Value

Pointer to a CFont object that is attached to the current font for the window.

Remarks

This method has no effect unless the window processes the WM_GETFONT message. Many MFC classes that derive from CWnd process this message because they are attached to a predefined window class that includes a message handler for the WM_GETFONT message. To use this method, classes that you derive from CWnd must define a method handler for the WM_GETFONT message.

Parameters

pcrKey
Pointer to a COLORREF value that receives the transparency color key to be used when composing the layered window. All pixels painted by the window in this color will be transparent. This can be NULL if the argument is not needed.

pbAlpha
Pointer to a BYTE that receives the Alpha value used to describe the opacity of the layered window. When the variable referred to by pbAlpha is 0, the window is completely transparent. When the variable referred to by pbAlpha is 255, the window is opaque. This can be NULL if the argument is not needed.

pdwFlags
Pointer to a DWORD that receives a layering flag. This can be NULL if the argument is not needed. For a complete list of possible values, see GetLayeredWindowAttributes.

Parameters

idObject
Specifies the menu object. For a list of possible values, see GetMenuBarInfo.

idItem
Specifies the item for which to retrieve information. If this parameter is zero, the function retrieves information about the menu itself. If this parameter is 1, the function retrieves information about the first item on the menu, and so on.

pmbi
Pointer to a MENUBARINFO structure that receives the information.

Return Value

Nonzero if the function succeeds; otherwise 0.

Remarks

This member function emulates the functionality of the function GetMenuBarInfo, as described in the Windows SDK.

Parameters

pWndCtl
Identifies the control to be used as the starting point for the search.

bPrevious
Specifies how the function is to search the group of controls in the dialog box. If TRUE, the function searches for the previous control in the group; if FALSE, it searches for the next control in the group.

pCurSiteOrWnd
Identifies the COleControlSiteOrWnd control. For more information about COleControlSiteOrWnd, see Remarks.

Return Value

Pointer to the previous or next control in the group if the member function is successful.

The returned pointer may be temporary and should not be stored for later use.

Remarks

A group of controls begins with a control that was created with the WS_GROUP style and ends with the last control that was not created with the WS_GROUP style.

By default, the GetNextDlgGroupItem member function returns a pointer to the next control in the group. If pWndCtl identifies the first control in the group and bPrevious is TRUE, GetNextDlgGroupItem returns a pointer to the last control in the group.

Note

Because MFC supports windowless ActiveX controls, standard ActiveX controls, and windows, referring to a control by only an HWND no longer suffices. The COleControlSiteOrWnd object includes information that identifies the object as a windowed ActiveX control, a windowless ActiveX control, or a window, as follows:

Control or window type

Identifying information

Windowed ActiveX control

Contains an HWND and associates a COleControlSite object with it. The m_hWnd member of COleControlSiteOrWnd is set to the HWND of the control, and the m_pSite member points to the control's COleControlSite.

Windowless ActiveX control

Contains no HWND. The m_pSite member of COleControlSiteOrWnd points to the control's COleControlSite, and the m_hWnd member is NULL.

Standard window

Contains just an HWND. The m_hWnd member of COleControlSiteOrWnd is set to the HWND of the window, and the m_pSite member is NULL.

Parameters

nFlag
Specifies whether the function returns a pointer to the next window or the previous window. It can be either GW_HWNDNEXT, which returns the window that follows the CWnd object on the window manager's list, or GW_HWNDPREV, which returns the previous window on the window manager's list.

Return Value

Identifies the next (or the previous) window in the window manager's list if the member function is successful.

The returned pointer may be temporary and should not be stored for later use.

Remarks

The window manager's list contains entries for all top-level windows, their associated child windows, and the child windows of any child windows.

If CWnd is a top-level window, the function searches for the next (or previous) top-level window; if CWnd is a child window, the function searches for the next (or previous) child window.

Return Value

Return Value

A pointer to a CWnd object.

Remarks

If the window has no owner, then a pointer to the parent window object is returned by default. Note that the relationship between the owner and the owned differs from the parent-child aspect in several important aspects. For example, a window with a parent is confined to its parent window's client area. Owned windows can be drawn at any location on the desktop.

The ownership concept of this function is different from the ownership concept of GetWindow.

Return Value

Remarks

The GetParent function returns a pointer to the immediate parent (if it exists). In contrast, the GetParentOwner function returns a pointer to the most immediate parent or owner window that is not a child window (does not have the WS_CHILD style). If you have a child window within a child window GetParent and GetParentOwner return different results.

Return Value

A pointer to a CWnd object. If a CWnd object is not attached to the handle, a temporary CWnd object is created and attached. The pointer may be temporary and should not be stored for later use.

Remarks

GetParentOwner returns a pointer to the most immediate parent or owner window that is not a child window (does not have the WS_CHILD style). The current owner window can be set with SetOwner. By default, the parent of a window is its owner.

In contrast, the GetParent function returns a pointer to the immediate parent, whether it is a child window or not. If you have a child window within a child window GetParent and GetParentOwner return different results.

Parameters

nBar
Specifies the type of scroll bar. The parameter can take one of the following values:

SB_HORZ Retrieves the position of the horizontal scroll bar.

SB_VERT Retrieves the position of the vertical scroll bar.

Return Value

A sibling scroll-bar control, or NULL if none.

Remarks

This member function does not operate on scroll bars created when the WS_HSCROLL or WS_VSCROLL bits are set during the creation of a window. The CWnd implementation of this function simply returns NULL. Derived classes, such as CView, implement the described functionality.

Parameters

nBar
Specifies whether the scroll bar is a control or part of a window's nonclient area. If it is part of the nonclient area, nBar also indicates whether the scroll bar is positioned horizontally, vertically, or both. It must be one of the following:

SB_CTL Retrieves the parameters for a scroll bar control. The m_hWnd data member must be the handle of the scroll bar control.

lpScrollInfo
A pointer to a SCROLLINFO structure. See the Windows SDK for more information about this structure.

nMask
Specifies the scroll bar parameters to retrieve. The default specifies a combination of SIF_PAGE, SIF_POS, SIF_TRACKPOS, and SIF_RANGE. See SCROLLINFO for more information on the nMask values.

Return Value

If the message retrieved any values, the return is TRUE. Otherwise, it is FALSE.

Remarks

GetScrollInfo enables applications to use 32-bit scroll positions.

The SCROLLINFO structure contains information about a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (the thumb). See the SCROLLINFO structure topic in the Windows SDK for more information about changing the structure defaults.

The MFC Windows message handlers that indicate scroll-bar position, CWnd::OnHScroll and CWnd::OnVScroll, provide only 16 bits of position data. GetScrollInfo and SetScrollInfo provide 32 bits of scroll-bar position data. Thus, an application can call GetScrollInfo while processing either CWnd::OnHScroll or CWnd::OnVScroll to obtain 32-bit scroll-bar position data.

Parameters

nBar
Specifies the scroll bar to examine. The parameter can take one of the following values:

SB_HORZ Retrieves the position of the horizontal scroll bar.

SB_VERT Retrieves the position of the vertical scroll bar.

Return Value

Specifies the current position of the scroll box in the scroll bar if successful; otherwise 0.

Remarks

The current position is a relative value that depends on the current scrolling range. For example, if the scrolling range is 50 to 100 and the scroll box is in the middle of the bar, the current position is 75.

Parameters

bRevert
Specifies the action to be taken. If bRevert is FALSE, GetSystemMenu returns a handle to a copy of the Control menu currently in use. This copy is initially identical to the Control menu but can be modified. If bRevert is TRUE, GetSystemMenu resets the Control menu back to the default state. The previous, possibly modified, Control menu, if any, is destroyed. The return value is undefined in this case.

Return Value

Identifies a copy of the Control menu if bRevert is FALSE. If bRevert is TRUE, the return value is undefined.

The returned pointer may be temporary and should not be stored for later use.

Remarks

Any window that does not use GetSystemMenu to make its own copy of the Control menu receives the standard Control menu.

The pointer returned by the GetSystemMenu member function can be used with the CMenu::AppendMenu, CMenu::InsertMenu, or CMenu::ModifyMenu functions to change the Control menu.

The Control menu initially contains items identified with various ID values such as SC_CLOSE, SC_MOVE, and SC_SIZE. Items on the Control menu generate WM_SYSCOMMAND messages. All predefined Control-menu items have ID numbers greater than 0xF000. If an application adds items to the Control menu, it should use ID numbers less than F000.

Windows may automatically make items unavailable on the standard Control menu. CWnd can carry out its own selection or unavailability by responding to the WM_INITMENU messages, which are sent before any menu is displayed.

Example

// The following code fragment is taken from CMyDlg::OnInitDialog// CMyDlg is derived from CDialog// Add "About..." menu item to system menu.// IDM_ABOUTBOX must be in the system command range.
ASSERT((IDM_ABOUTBOX & 0xFFF0) == IDM_ABOUTBOX);
ASSERT(IDM_ABOUTBOX < 0xF000);
CMenu* pSysMenu = GetSystemMenu(FALSE);
if (pSysMenu != NULL)
{
CString strAboutMenu;
strAboutMenu.LoadString(IDS_ABOUT);
if (!strAboutMenu.IsEmpty())
{
pSysMenu->AppendMenu(MF_SEPARATOR);
pSysMenu->AppendMenu(MF_STRING, IDM_ABOUTBOX, strAboutMenu);
}
}
// Set the icon for this dialog. The framework does this automatically// when the application's main window is not a dialog
SetIcon(m_hIcon, TRUE); // Set big icon
SetIcon(m_hIcon, FALSE); // Set small icon

Parameters

lpRect
Points to a CRect object or RECT structure that is to receive the client coordinates of the update that encloses the update region.

Set this parameter to NULL to determine whether an update region exists within the CWnd. If lpRect is NULL, the GetUpdateRect member function returns nonzero if an update region exists and 0 if one does not. This provides a way to determine whether a WM_PAINT message resulted from an invalid area. Do not set this parameter to NULL in Windows version 3.0 and earlier.

bErase
Specifies whether the background in the update region is to be erased.

Return Value

Specifies the status of the update region. The value is nonzero if the update region is not empty; otherwise 0.

If the lpRect parameter is set to NULL, the return value is nonzero if an update region exists; otherwise 0.

Remarks

If CWnd was created with the CS_OWNDC style and the mapping mode is not MM_TEXT, the GetUpdateRect member function gives the rectangle in logical coordinates. Otherwise, GetUpdateRect gives the rectangle in client coordinates. If there is no update region, GetUpdateRect sets the rectangle to be empty (sets all coordinates to 0).

The bErase parameter specifies whether GetUpdateRect should erase the background of the update region. If bErase is TRUE and the update region is not empty, the background is erased. To erase the background, GetUpdateRect sends the WM_ERASEBKGND message.

The update rectangle retrieved by the BeginPaint member function is identical to that retrieved by the GetUpdateRect member function.

The BeginPaint member function automatically validates the update region, so any call to GetUpdateRect made immediately after a call to BeginPaint retrieves an empty update region.

Return Value

Identifies the display context for the given window if the function is successful; otherwise NULL.

The returned pointer may be temporary and should not be stored for later use. ReleaseDC should be called once for each successful call to GetWindowDC.

Remarks

A window display context permits painting anywhere in CWnd, since the origin of the context is the upper-left corner of CWnd instead of the client area.

Default attributes are assigned to the display context each time it retrieves the context. Previous attributes are lost.

GetWindowDC is intended to be used for special painting effects within the CWnd nonclient area. Painting in nonclient areas of any window is not recommended.

The GetSystemMetrics Windows function can be used to retrieve the dimensions of various parts of the nonclient area, such as the caption bar, menu, and scroll bars.

After painting is complete, the ReleaseDC member function must be called to release the display context. Failure to release the display context will seriously affect painting requested by applications due to limitations on the number of device contexts that can be open at the same time.

Parameters

lpwndpl
Points to the WINDOWPLACEMENT structure that receives the show state and position information.

Return Value

Nonzero if the function is successful; otherwise 0.

Remarks

The flags member of the WINDOWPLACEMENT structure retrieved by this function is always 0. If CWnd is maximized, the showCmd member of WINDOWPLACEMENT is SW_SHOWMAXIMIZED. If the window is minimized, it is SW_SHOWMINIMIZED. It is SW_SHOWNORMAL otherwise.

Parameters

Return Value

The return value specifies the type of the region that the function obtains. It can be one of the following values:

NULLREGION The region is empty.

SIMPLEREGION The region is a single rectangle.

COMPLEXREGION The region is more than one rectangle.

ERROR An error occurred; the region is unaffected.

Remarks

The window region determines the area within the window where the operating system permits drawing. The operating system does not display any portion of a window that lies outside of the window region.

The coordinates of a window's window region are relative to the upper-left corner of the window, not the client area of the window.

Parameters

lpszStringBuf
Points to the buffer that is to receive the copied string of the window's title.

nMaxCount
Specifies the maximum number of characters to be copied to the buffer, including the terminating null character. If the string is longer than the number of characters specified in nMaxCount, it is truncated.

rString
A CString object that is to receive the copied string of the window's title.

Return Value

Specifies the length, in characters, of the copied string, not including the terminating null character. It is 0 if CWnd has no caption or if the caption is empty.

Remarks

If the CWnd object is a control, the GetWindowText member function copies the text within the control instead of copying the caption.

This member function causes the WM_GETTEXT message to be sent to the CWnd object.

Parameters

pMenu
Identifies the top-level menu that contains the item to be highlighted.

nIDHiliteItem
Specifies the menu item to be highlighted, depending on the value of the nHilite parameter.

nHilite
Specifies whether the menu item is highlighted or the highlight is removed. It can be a combination of MF_HILITE or MF_UNHILITE with MF_BYCOMMAND or MF_BYPOSITION. The values can be combined using the bitwise OR operator. These values have the following meanings:

MF_BYCOMMAND Interprets nIDHiliteItem as the menu-item ID (the default interpretation).

MF_BYPOSITION Interprets nIDHiliteItem as the zero-based offset of the menu item.

MF_HILITE Highlights the item. If this value is not given, the highlight is removed from the item.

MF_UNHILITE Removes the highlight from the item.

Return Value

Specifies whether the menu item was highlighted. Nonzero if the item was highlighted; otherwise 0.

Remarks

The MF_HILITE and MF_UNHILITE flags can be used only with this member function; they cannot be used with the CMenu::ModifyMenu member function.

Parameters

dwData
Specifies additional data. The value used depends on the value of the nCmd parameter.

nCmd
Specifies the type of help requested. For a list of possible values and how they affect the dwData parameter, see the uCommand parameter described in the HTML Help API Reference in the Windows SDK.

Remarks

Parameters

bErase
Specifies whether the background within the update region is to be erased.

Remarks

The client area is marked for painting when the next WM_PAINT message occurs. The region can also be validated before a WM_PAINT message occurs by the ValidateRect or ValidateRgn member function.

The bErase parameter specifies whether the background within the update area is to be erased when the update region is processed. If bErase is TRUE, the background is erased when the BeginPaint member function is called; if bErase is FALSE, the background remains unchanged. If bErase is TRUE for any part of the update region, the background in the entire region, not just in the given part, is erased.

Windows sends a WM_PAINT message whenever the CWnd update region is not empty and there are no other messages in the application queue for that window.

Parameters

lpRect
Points to a CRect object or a RECT structure that contains the rectangle (in client coordinates) to be added to the update region. If lpRect is NULL, the entire client area is added to the region.

bErase
Specifies whether the background within the update region is to be erased.

Remarks

The invalidated rectangle, along with all other areas in the update region, is marked for painting when the next WM_PAINT message is sent. The invalidated areas accumulate in the update region until the region is processed when the next WM_PAINT call occurs, or until the region is validated by the ValidateRect or ValidateRgn member function.

The bErase parameter specifies whether the background within the update area is to be erased when the update region is processed. If bErase is TRUE, the background is erased when the BeginPaint member function is called; if bErase is FALSE, the background remains unchanged. If bErase is TRUE for any part of the update region, the background in the entire region is erased, not just in the given part.

Windows sends a WM_PAINT message whenever the CWnd update region is not empty and there are no other messages in the application queue for that window.

Parameters

pRgn
A pointer to a CRgn object that identifies the region to be added to the update region. The region is assumed to have client coordinates. If this parameter is NULL, the entire client area is added to the update region.

bErase
Specifies whether the background within the update region is to be erased.

Remarks

The invalidated region, along with all other areas in the update region, is marked for painting when the WM_PAINT message is next sent. The invalidated areas accumulate in the update region until the region is processed when a WM_PAINT message is next sent, or until the region is validated by the ValidateRect or ValidateRgn member function.

The bErase parameter specifies whether the background within the update area is to be erased when the update region is processed. If bErase is TRUE, the background is erased when the BeginPaint member function is called; if bErase is FALSE, the background remains unchanged. If bErase is TRUE for any part of the update region, the background in the entire region, not just in the given part, is erased.

Windows sends a WM_PAINT message whenever the CWnd update region is not empty and there are no other messages in the application queue for that window.

The given region must have been previously created by one of the region functions.

pvRet
Address of the variable that will that will receive the property value or return value. It must match the type specified by vtRet.

pbParamInfo
Pointer to a null-terminated string of bytes specifying the types of the parameters following pbParamInfo. For possible values, see the Remarks section for COleDispatchDriver::InvokeHelper.

...
Variable List of parameters, of types specified in pbParamInfo.

Remarks

The pbParamInfo parameter specifies the types of the parameters passed to the method or property. The variable list of arguments is represented by ... in the syntax declaration.

This function converts the parameters to VARIANTARG values, then invokes the IDispatch::Invoke method on the ActiveX control. If the call to IDispatch::Invoke fails, this function will throw an exception. If the SCODE (status code) returned by IDispatch::Invoke is DISP_E_EXCEPTION, this function throws a COleException object, otherwise it throws a COleDispatchException.

Note

This function should be called only on a CWnd object that represents an ActiveX control.

Parameters

lpMsg
Points to an MSG structure that contains the message to be checked.

Return Value

Specifies whether the member function has processed the given message. It is nonzero if the message has been processed; otherwise 0. If the return is 0, call the CWnd::PreTranslateMessage member function of the base class to process the message. In an override of the CWnd::PreTranslateMessage member function the code looks like this :

Remarks

When the IsDialogMessage function processes a message, it checks for keyboard messages and converts them to selection commands for the corresponding dialog box. For example, the TAB key selects the next control or group of controls, and the DOWN ARROW key selects the next control in a group.

You must not pass a message processed by IsDialogMessage to the TranslateMessage or DispatchMessage Windows functions, because it has already been processed.

Parameters

nIDButton
Specifies the integer identifier of the button control.

Return Value

Nonzero if the given control is checked, and 0 if it is not checked. Only radio buttons and check boxes can be checked. For three-state buttons, the return value can be 2 if the button is indeterminate. This member function returns 0 for a pushbutton.

Remarks

If the button is a three-state control, the member function determines whether it is dimmed, checked, or neither.

Return Value

Nonzero if CWnd is visible (has the WS_VISIBLE style bit set, and parent window is visible). Because the return value reflects the state of the WS_VISIBLE style bit, the return value may be nonzero even though CWnd is totally obscured by other windows.

Remarks

A window possesses a visibility state indicated by the WS_VISIBLE style bit. When this style bit is set with a call to the ShowWindow member function, the window is displayed and subsequent drawing to the window is displayed as long as the window has the style bit set.

Any drawing to a window that has the WS_VISIBLE style will not be displayed if the window is covered by other windows or is clipped by its parent window.

Example

// This example uses the CWnd::IsWindowVisible() function to// determine if a dialog box is visible. If it is not, it calls// CWnd::ShowWindow with the SW_SHOWNORMAL command.void CMainFrame::DisplayModeless()
{
if(!m_Modeless.IsWindowVisible())
{
m_Modeless.ShowWindow(SW_SHOWNORMAL);
}
}
// This example uses the CWnd::IsWindowVisible() function to// determine if a dialog box is visible. If it is, it calls// CWnd::ShowWindow with the SW_HIDE command.void CMainFrame::HideModeless()
{
if(m_Modeless.IsWindowVisible())
{
m_Modeless.ShowWindow(SW_HIDE);
}
}

Remarks

Return Value

Nonzero if the function is successful. It is 0 if a failure occurs or if the LockWindowUpdate function has been used to lock another window.

Remarks

A locked window cannot be moved. Only one window can be locked at a time. To unlock a window locked with LockWindowUpdate, call UnlockWindowUpdate.

If an application with a locked window (or any locked child windows) calls the GetDC,GetDCEx, or BeginPaint Windows function, the called function returns a device context whose visible region is empty. This will occur until the application unlocks the window by calling the UnlockWindowUpdate member function.

While window updates are locked, the system keeps track of the bounding rectangle of any drawing operations to device contexts associated with a locked window. When drawing is reenabled, this bounding rectangle is invalidated in the locked window and its child windows to force an eventual WM_PAINT message to update the screen. If no drawing has occurred while the window updates were locked, no area is invalidated.

The LockWindowUpdate member function does not make the given window invisible and does not clear the WS_VISIBLE style bit.

Example

void CMainFrame::OnDisplayErrorMessage()
{
// This displays a message box with the title "Error"// and the message "Help, Something went wrong."// The error icon is displayed in the message box, along with// an OK button.
MessageBox(_T("Help, Something went wrong."), _T("Error"),
MB_ICONERROR | MB_OK);
}

For some styles in certain controls (the ES_READONLY style in the edit control, for example), ModifyStyle may not properly change the style because the control may need to perform special internal processing. In these cases, a corresponding message to change the style will be available ( EM_SETREADONLY in the example mentioned).

Parameters

dwRemove
Specifies extended styles to be removed during style modification.

dwAdd
Specifies extended styles to be added during style modification.

nFlags
Flags to be passed to SetWindowPos, or zero if SetWindowPos should not be called. The default is zero. See the Remarks section for a list of preset flags.

Return Value

Nonzero if style was successfully modified; otherwise, 0.

Remarks

Styles to be added or removed can be combined by using the bitwise OR (|) operator. See the topics Extended Window Styles in this book and CreateWindowEx in the Windows SDK for information about the available extended styles

If nFlags is nonzero, ModifyStyleEx calls the Windows API function SetWindowPos and redraws the window by combining nFlags with the following four preset flags:

Parameters

x
Specifies the new position of the left side of the CWnd.

y
Specifies the new position of the top of the CWnd.

nWidth
Specifies the new width of the CWnd.

nHeight
Specifies the new height of the CWnd.

bRepaint
Specifies whether CWnd is to be repainted. If TRUE, CWnd receives a WM_PAINT message in its OnPaint message handler as usual. If this parameter is FALSE, no repainting of any kind occurs. This applies to the client area, to the nonclient area (including the title and scroll bars), and to any part of the parent window uncovered as a result of CWnd's move. When this parameter is FALSE, the application must explicitly invalidate or redraw any parts of CWnd and parent window that must be redrawn.

Remarks

For a top-level CWnd object, the x and y parameters are relative to the upper-left corner of the screen. For a child CWnd object, they are relative to the upper-left corner of the parent window's client area.

The MoveWindow function sends the WM_GETMINMAXINFO message. Handling this message gives CWnd the opportunity to modify the default values for the largest and smallest possible windows. If the parameters to the MoveWindow member function exceed these values, the values can be replaced by the minimum or maximum values in the WM_GETMINMAXINFO handler.

Parameters

event
Specifies the event that occurred. This value must be one of the event constants.

idObjectType
Identifies the kind of object that generated the event. This value is one of the predefined object identifiers or a custom object ID value.

idObject
Identifies whether the event was generated by an object or a child element of the object. If this value is CHILDID_SELF, the event was generated by the object itself. If not, this value is the child ID of the element that generated the event.

Remarks

This member function emulates the functionality of the function NotifyWinEvent, as described in the Windows SDK.

Parameters

nState
Specifies whether the CWnd is being activated or deactivated. It can be one of the following values:

WA_INACTIVE The window is being deactivated.

WA_ACTIVE The window is being activated through some method other than a mouse click (for example, by use of the keyboard interface to select the window).

WA_CLICKACTIVE The window is being activated by a mouse click.

pWndOther
Pointer to the CWnd being activated or deactivated. The pointer can be NULL, and it may be temporary.

bMinimized
Specifies the minimized state of the CWnd being activated or deactivated. A value of TRUE indicates the window is minimized.

If TRUE, the CWnd is being activated; otherwise deactivated.

Remarks

If the CWnd object is activated with a mouse click, it will also receive an OnMouseActivate member function call.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bActive
Specifies whether the CWnd is being activated or deactivated. TRUE means the CWnd is being activated. FALSE means the CWnd is being deactivated.

dwThreadID
Specifies the value of the thread ID. If bActive is TRUE, dwThreadID identifies the thread that owns the CWnd being deactivated. If bActive is FALSE, dwThreadID identifies the thread that owns the CWnd being activated.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pSite
Pointer to the site of the control that requested the ambient property.

dispid
The dispatch ID of the requested ambient property.

pvar
Pointer to a caller-allocated VARIANT structure, through which the ambient property's value will be returned.

Return Value

TRUE if the ambient property is supported; FALSE if not.

Remarks

Override this function to alter the default ambient property values returned by an OLE control container to its controls. Any ambient property requests not handled by an overriding function should be forwarded to the base class implementation.

The framework calls this member function when the user generates an application command event. Such an event occurs when the user clicks an application command button or types an application command key.

Parameters

Pointer to a CWnd object that represents the window where the user clicked the comman button or pressed the command key. This window can be a child window of the window receiving the message.

[in] nCmd

Indicates the application command. For a list of possible values, see the commands under the cmd section of the lParam parameter of WM_APPCOMMAND.

[in] nDevice

The input device that generated the input event. For a list of possible values, see the devices under the uDevice section of the lParam parameter of WM_APPCOMMAND.

[in] nKey

Indicates any virtual keys that are down, such as the CTRL key or the left mouse button. For a list of possible values, see the keys under the dwKeys section of the lParam parameter of WM_APPCOMMAND. For more information, see the "Message Parameters" subheading in About Mouse Input.

Remarks

This method receives the WM_APPCOMMAND notification, which is described in the Windows SDK.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

lpszString
Points to the buffer where the copy of the format name is to be stored.

Remarks

The Clipboard owner should provide a name for its format.

Override this member function and copy the name of the CF_OWNERDISPLAY format into the specified buffer, not exceeding the maximum number of bytes specified.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pWnd
A pointer to the window to gain mouse capture

Remarks

A window receives this message even if it calls ReleaseCapture itself. An application should not attempt to set the mouse capture in response to this message. When it receives this message, a window should redraw itself, if necessary, to reflect the new mouse-capture state.

See the Windows SDK for information on the ReleaseCapture Windows function.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

hWndRemove
Specifies the window handle that is being removed from the Clipboard-viewer chain.

hWndAfter
Specifies the window handle that follows the window being removed from the Clipboard-viewer chain.

Remarks

Each CWnd object that receives an OnChangeCbChain call should use the SendMessage Windows function to send the WM_CHANGECBCHAIN message to the next window in the Clipboard-viewer chain (the handle returned by SetClipboardViewer). If hWndRemove is the next window in the chain, the window specified by hWndAfter becomes the next window, and Clipboard messages are passed on to it.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nRepCnt
Contains the repeat count, the number of times the keystroke is repeated when user holds down the key.

nFlags
Contains the scan code, key-transition code, previous key state, and context code, as shown in the following list:

Value

Meaning

0-15

Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.

16-23

Specifies the scan code. The value depends on the original equipment manufacturer (OEM)

24

Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.

25-28

Used internally by Windows.

29

Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.

30

Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.

31

Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.

Remarks

This function is called before the OnKeyUp member function and after the OnKeyDown member function are called. OnChar contains the value of the keyboard key being pressed or released.

Because there is not necessarily a one-to-one correspondence between keys pressed and OnChar calls generated, the information in nFlags is generally not useful to applications. The information in nFlags applies only to the most recent call to the OnKeyUp member function or the OnKeyDown member function that precedes the call to OnChar.

For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the slash (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in nFlags.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nChar
Specifies the value of the key pressed by the user.

pListBox
Specifies a pointer to the list box. It may be temporary.

nIndex
Specifies the current caret position.

Return Value

The framework calls this member function to specify the action that the application performed in response to the call. A return value of –2 indicates that the application handled all aspects of selecting the item and wants no further action by the list box. A return value of –1 indicates that the list box should perform the default action in response to the keystroke. A return value of 0 or greater specifies the zero-based index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the given item.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

If the CWnd object is a multiple document interface (MDI) child window, OnChildActivate is called by the framework when the user clicks the window's title bar or when the window is activated, moved, or sized.

Parameters

Parameter

Description

[in] dwColorizationColor

Specifies the new colorization color.

The color format is a hexadecimal number of the form 0xAARRGGBB, where each of the four components ranges from 0x00 through 0xFF. The AA component is the alpha value, RR is the color red, GG is green, and BB is blue.

[in] bOpacity

true if the new color is blended with opacity; false if it is not.

Remarks

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

wParam
The low-order word of wParam identifies the command ID of the menu item, control, or accelerator. The high-order word of wParam specifies the notification message if the message is from a control. If the message is from an accelerator, the high-order word is 1. If the message is from a menu, the high-order word is 0.

lParam
Identifies the control that sends the message if the message is from a control. Otherwise, lParam is 0.

Return Value

An application returns nonzero if it processes this message; otherwise 0.

Remarks

OnCommand processes the message map for control notification and ON_COMMAND entries, and calls the appropriate member function.

Override this member function in your derived class to handle the WM_COMMAND message. An override will not process the message map unless the base class OnCommand is called.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nCpuTime
Specifies the ratio of CPU time currently spent by Windows compacting memory to CPU time spent performing other operations. For example, 8000h represents 50 percent of CPU time spent compacting memory.

Remarks

This indicates that system memory is low.

When a CWnd object receives this call, it should free as much memory as possible, taking into account the current level of activity of the application and the total number of applications running in Windows. The application can call the Windows function to determine how many applications are running.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nIDCtl
The identifier of the control that sent the WM_COMPAREITEM message.

lpCompareItemStruct
Contains a long pointer to a COMPAREITEMSTRUCT data structure that contains the identifiers and application-supplied data for two items in the combo or list box.

Return Value

Indicates the relative position of the two items. It may be any of the following values:

Value

Meaning

–1

Item 1 sorts before item 2.

0

Item 1 and item 2 sort the same.

1

Item 1 sorts after item 2.

Remarks

If a combo or list box is created with the CBS_SORT or LBS_SORT style, Windows sends the combo-box or list-box owner a WM_COMPAREITEM message whenever the application adds a new item.

Two items in the combo or list box are reformed in a COMPAREITEMSTRUCT structure pointed to by lpCompareItemStruct. OnCompareItem should return a value that indicates which of the items should appear before the other. Typically, Windows makes this call several times until it determines the exact position for the new item.

If the hwndItem member of the COMPAREITEMSTRUCT structure belongs to a CListBox or CComboBox object, then the CompareItem virtual function of the appropriate class is called. Override CComboBox::CompareItem or CListBox::CompareItem in your derived CListBox or CComboBox class to do the item comparison.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pWnd
Handle to the window in which the user right clicked the mouse. This can be a child window of the window receiving the message. For more information about processing this message, see the Remarks section.

pos
Position of the cursor, in screen coordinates, at the time of the mouse click.

Remarks

You can process this message by displaying a context menu using the TrackPopupMenu.

If you do not display a context menu you should pass this message onto the DefWindowProc function. If your window is a child window, DefWindowProc sends the message to the parent. Otherwise, DefWindowProc displays a default context menu if the specified position is in the window's caption.

Return Value

Remarks

The data being passed must not contain pointers or other references to objects not accessible to the application receiving the data.

While the data is being copied, it must not be changed by another thread of the sending process.

The receiving application should consider the data read-only. The structure pointed to by the parameter pCopyDataStruct is valid only during the transfer of data; however, the receiving application should not free the memory associated with the structure.

If the receiving application needs access to the data after this function returns, it must copy the data received to a local buffer.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

lpCreateStruct
Points to a CREATESTRUCT structure that contains information about the CWnd object being created.

Return Value

OnCreate must return 0 to continue the creation of the CWnd object. If the application returns –1, the window will be destroyed.

Remarks

The CWnd object receives this call after the window is created but before it becomes visible. OnCreate is called before the Create or CreateEx member function returns.

Override this member function to perform any needed initialization of a derived class.

The CREATESTRUCT structure contains copies of the parameters used to create the window.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pDC
Contains a pointer to the display context for the child window. May be temporary.

pWnd
Contains a pointer to the control asking for the color. May be temporary.

nCtlColor
Contains one of the following values, specifying the type of control:

CTLCOLOR_BTN Button control

CTLCOLOR_DLG Dialog box

CTLCOLOR_EDIT Edit control

CTLCOLOR_LISTBOX List-box control

CTLCOLOR_MSGBOX Message box

CTLCOLOR_SCROLLBAR Scroll-bar control

CTLCOLOR_STATIC Static control

Return Value

OnCtlColor must return a handle to the brush that is to be used for painting the control background.

Remarks

Most controls send this message to their parent (usually a dialog box) to prepare the pDC for drawing the control using the correct colors.

To change the text color, call the SetTextColor member function with the desired red, green, and blue (RGB) values.

To change the background color of a single-line edit control, set the brush handle in both the CTLCOLOR_EDIT and CTLCOLOR_MSGBOX message codes, and call the CDC::SetBkColor function in response to the CTLCOLOR_EDIT code.

OnCtlColor will not be called for the list box of a drop-down combo box because the drop-down list box is actually a child of the combo box and not a child of the window. To change the color of the drop-down list box, create a CComboBox with an override of OnCtlColor that checks for CTLCOLOR_LISTBOX in the nCtlColor parameter. In this handler, the SetBkColor member function must be used to set the background color for the text.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function. To add the following method to your dialog class, use the Visual Studio properties pane to add a message handler for WM_CTLCOLOR. Alternatively, you can manually add an ON_WM_CTLCOLOR() entry to the message map.

Example

// This OnCtlColor handler will change the color of a static control// with the ID of IDC_MYSTATIC. The code assumes that the CPenWidthsDlg// class has an initialized and created CBrush member named m_brush.// The control will be painted with red text and a background// color of m_brush.
HBRUSH CPenWidthsDlg::OnCtlColor(CDC* pDC, CWnd* pWnd, UINT nCtlColor)
{
// Call the base class implementation first! Otherwise, it may// undo what we're trying to accomplish here.
HBRUSH hbr = CDialog::OnCtlColor(pDC, pWnd, nCtlColor);
// Are we painting the IDC_MYSTATIC control? We can use// CWnd::GetDlgCtrlID() to perform the most efficient test.if (pWnd->GetDlgCtrlID() == IDC_MYSTATIC)
{
// Set the text color to red
pDC->SetTextColor(RGB(255, 0, 0));
// Set the background mode for text to transparent // so background will show thru.
pDC->SetBkMode(TRANSPARENT);
// Return handle to our CBrush object
hbr = m_brush;
}
return hbr;
}

Parameters

nFlags
Specifies the scan code, key-transition code, previous key state, and context code, as shown in the following list:

Value

Description

0–7

Scan code (OEM-dependent value). Low byte of high-order word.

8

Extended key, such as a function key or a key on the numeric keypad (1 if it is an extended key; otherwise 0).

9–10

Not used.

11–12

Used internally by Windows.

13

Context code (1 if the ALT key is held down while the key is pressed; otherwise 0).

14

Previous key state (1 if the key is down before the call, 0 if the key is up).

15

Transition state (1 if the key is being released, 0 if the key is being pressed).

Remarks

This member function can be used to specify the character value of a dead key. A dead key is a key, such as the umlaut (double-dot) character, that is combined with other characters to form a composite character. For example, the umlaut-O character consists of the dead key, umlaut, and the O key.

An application typically uses OnDeadChar to give the user feedback about each key pressed. For example, an application can display the accent in the current character position without moving the caret.

Since there is not necessarily a one-to-one correspondence between keys pressed and OnDeadChar calls, the information in nFlags is generally not useful to applications. The information in nFlags applies only to the most recent call to the OnKeyUp member function or the OnKeyDown member function that precedes the OnDeadChar call.

For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the slash (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in nFlags.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nIDCtl
The identifier of the control that sent the WM_DELETEITEM message.

lpDeleteItemStruct
Specifies a long pointer to a DELETEITEMSTRUCT data structure that contains information about the deleted list box item.

Remarks

If the hwndItem member of the DELETEITEMSTRUCT structure belongs to a combo box or list box, then the DeleteItem virtual function of the appropriate class is called. Override the DeleteItem member function of the appropriate control's class to delete item-specific data.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

OnDestroy is called first for the CWnd being destroyed, then for the child windows of CWnd as they are destroyed. It can be assumed that all child windows still exist while OnDestroy runs.

If the CWnd object being destroyed is part of the Clipboard-viewer chain (set by calling the SetClipboardViewer member function), the CWnd must remove itself from the Clipboard-viewer chain by calling the ChangeClipboardChain member function before returning from the OnDestroy function.

Parameters

nEventType
An event type. See the Remarks section for a description of the available values

dwData
The address of a structure that contains event-specific data. Its meaning depends on the given event.

Remarks

For devices that offer software-controllable features, such as ejection and locking, the operating system typically sends a DBT_DEVICEREMOVEPENDING message to let applications and device drivers end their use of the device gracefully.

If the operating system forcefully removes of a device, it may not send a DBT_DEVICEQUERYREMOVE message before doing so.

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

lpDeviceName
Points to the device name specified in the Windows initialization file, WIN.INI.

Remarks

Applications that handle the WM_DEVMODECHANGE message may reinitialize their device-mode settings. Applications that use the Windows ExtDeviceMode function to save and restore device settings typically do not process this function.

This function is not called when the user changes the default printer from Control Panel. In this case, the OnWinIniChange function is called.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

Only applications that have joined the Clipboard-viewer chain by calling the SetClipboardViewer member function need to respond to this call.

Each window that receives an OnDrawClipboard call should call the SendMessage Windows function to pass a WM_DRAWCLIPBOARD message on to the next window in the Clipboard-viewer chain. The handle of the next window is returned by the SetClipboardViewer member function; it may be modified in response to an OnChangeCbChain member function call.

Parameters

szRequiredThumbnailSize
Specifies the size of the target thumbnail. Should be ignored if bIsThumbnail is FALSE.

bIsThumbnail
Specifies whether this method is called for iconic thumbnail or live preview (peek).

bAlphaChannelSet
[out] Set it to TRUE if your implementation initializes the alpha channel of a bitmap selected in dc.

Remarks

Override this method in a derived class and draw on the specified device context in order to customize thumbnail and peek. If bThumbnail is TRUE, szRequiredThumbnailSize can be ignored. In this case you should be aware that you draw full sized bitmap (that is, a bitmap that covers the whole client area). The device context ( dc) comes with selected 32 bits bitmap. The default implementation sends WM_PRINT to this window with PRF_CLIENT, PRF_CHILDREN, and PRF_NONCLIENT flags.

Parameters

nIDCtl
Contains the identifier of the control that sent the WM_DRAWITEM message. If a menu sent the message, nIDCtl contains 0.

lpDrawItemStruct
Specifies a long pointer to a DRAWITEMSTRUCT data structure that contains information about the item to be drawn and the type of drawing required.

Remarks

The itemAction member of the DRAWITEMSTRUCT structure defines the drawing operation that is to be performed. The data in this member allows the owner of the control to determine what drawing action is required.

Before returning from processing this message, an application should ensure that the device context identified by the hDC member of the DRAWITEMSTRUCT structure is restored to the default state.

If the hwndItem member belongs to a CButton, CMenu, CListBox, or CComboBox object, then the DrawItem virtual function of the appropriate class is called. Override the DrawItem member function of the appropriate control's class to draw the item.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

hDropInfo
A pointer to an internal data structure that describes the dropped files. This handle is used by the DragFinish, DragQueryFile, and DragQueryPoint Windows functions to retrieve information about the dropped files.

Remarks

Typically, a derived class will be designed to support dropped files and it will register itself during window construction.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bEnable
Specifies whether the CWnd object has been enabled or disabled. This parameter is TRUE if the CWnd has been enabled; it is FALSE if the CWnd has been disabled.

Remarks

OnEnable is called before the EnableWindow member function returns, but after the window enabled state ( WS_DISABLED style bit) has changed.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bEnding
Specifies whether or not the session is being ended. It is TRUE if the session is being ended; otherwise FALSE.

Remarks

The OnEndSession call informs the CWnd object whether the session is actually ending.

If bEnding is TRUE, Windows can terminate any time after all applications have returned from processing this call. Consequently, have an application perform all tasks required for termination within OnEndSession.

You do not need to call the DestroyWindow member function or PostQuitMessage Windows function when the session is ending.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nWhy
Specifies whether the message is the result of a dialog box or a menu being displayed. This parameter can be one of the following values:

MSGF_DIALOGBOX The system is idle because a dialog box is being displayed.

MSGF_MENU The system is idle because a menu is being displayed.

pWho
Specifies a pointer to the dialog box (if nWhy is MSGF_DIALOGBOX), or the window that contains the displayed menu (if nWhy is MSGF_MENU). This pointer may be temporary and should not be stored for later use.

Remarks

A modal dialog box or menu enters an idle state when no messages are waiting in its queue after it has processed one or more previous messages.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bIsTrackPopupMenu
Specifies whether the menu involved is a popup menu. Has a nonzero value if the function is successful; otherwise 0.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This method receives the WM_ENTERSIZEMOVE notification, which is described in the Windows SDK.

A window enters a moving or sizing modal loop when the user clicks the window's title bar or sizing border, or when the window passes the WM_SYSCOMMAND message to the CWnd::DefWindowProc function and the wParam parameter of that message specifies SC_MOVE or SC_SIZE.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

Return Value

Remarks

The default implementation erases the background using the window class background brush specified by the hbrBackground member of the window class structure.

If the hbrBackground member is NULL, your overridden version of OnEraseBkgnd should erase the background color. Your version should also align the origin of the intended brush with the CWnd coordinates by first calling UnrealizeObject for the brush, and then selecting the brush.

An overridden OnEraseBkgnd should return nonzero in response to WM_ERASEBKGND if it processes the message and erases the background; this indicates that no further erasing is required. If it returns 0, the window will remain marked as needing to be erased. (Typically, this means that the fErase member of the PAINTSTRUCT structure will be TRUE.)

Windows assumes the background is computed with the MM_TEXT mapping mode. If the device context is using any other mapping mode, the area erased may not be within the visible part of the client area.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bIsTrackPopupMenu
Specifies whether the menu involved is a pop-up menu. Has a nonzero value if the function is successful; otherwise 0.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This method receives the WM_EXITSIZEMOVE notification, which is described in the Windows SDK.

A window enters a moving or sizing modal loop when the user clicks the window's title bar or sizing border, or when the window passes the WM_SYSCOMMAND message to the CWnd::DefWindowProc function and the wParam parameter of that message specifies SC_MOVE or SC_SIZE.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Return Value

One or more of the following values, indicating which type of input the application processes:

DLGC_BUTTON Button (generic).

DLGC_DEFPUSHBUTTON Default pushbutton.

DLGC_HASSETSEL EM_SETSEL messages.

DLGC_UNDEFPUSHBUTTON No default pushbutton processing. (An application can use this flag with DLGC_BUTTON to indicate that it processes button input but relies on the system for default pushbutton processing.)

DLGC_RADIOBUTTON Radio button.

DLGC_STATIC Static control.

DLGC_WANTALLKEYS All keyboard input.

DLGC_WANTARROWS Arrow keys.

DLGC_WANTCHARSWM_CHAR messages.

DLGC_WANTMESSAGE All keyboard input. The application passes this message on to the control.

DLGC_WANTTAB TAB key.

Remarks

Normally, Windows handles all arrow-key and TAB-key input to a CWnd control. By overriding OnGetDlgCode, a CWnd control can choose a particular type of input to process itself.

The default OnGetDlgCode functions for the predefined control classes return a code appropriate for each class.

Parameters

lpMMI
Points to a MINMAXINFO structure that contains information about a window's maximized size and position and its minimum and maximum tracking size. For more about this structure, see the MINMAXINFO structure.

Remarks

The maximized size is the size of the window when its borders are fully extended. The maximum tracking size of the window is the largest window size that can be achieved by using the borders to size the window. The minimum tracking size of the window is the smallest window size that can be achieved by using the borders to size the window.

Windows fills in an array of points specifying default values for the various positions and dimensions. The application may change these values in OnGetMinMaxInfo.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

Parameters

lpHelpInfo
Pointer to a HELPINFO structure that contains information about the menu item, control, dialog box, or window for which help is requested.

Return Value

Returns TRUE if a window has the keyboard focus or if a menu is active within a window. If no window has the keyboard focus, returns FALSE.

Remarks

If a menu is active when F1 is pressed, WM_HELP is sent to the window associated with the menu; otherwise, WM_HELP is sent to the window that has the keyboard focus. If no window has the keyboard focus, WM_HELP is sent to the currently active window.

A bitwise combination (OR) of flags that indicate the keys that were pressed in combination with the key specified by the nKey2 parameter. The possible values are:

- MOD_ALT - Either ALT key was held down.- MOD_CONTROL - Either CTRL key was held down.- MOD_SHIFT - Either SHIFT key was held down.- MOD_WIN - Either WINDOWS key was held down. These keys are labeled with the Microsoft Windows logo.

[in] nKey2

The virtual key code of the hot key.

Remarks

This method receives the WM_HOTKEY notification, which is described in the Windows SDK. This message is placed at the top of the message queue associated with the thread that registered the hot key. Use the RegisterHotKey function to register a system-wide hot key.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nSBCode
Specifies a scroll-bar code that indicates the user's scrolling request. This parameter can be one of the following:

SB_LEFT Scroll to far left.

SB_ENDSCROLL End scroll.

SB_LINELEFT Scroll left.

SB_LINERIGHT Scroll right.

SB_PAGELEFT Scroll one page left.

SB_PAGERIGHT Scroll one page right.

SB_RIGHT Scroll to far right.

SB_THUMBPOSITION Scroll to absolute position. The current position is specified by the nPos parameter.

SB_THUMBTRACK Drag scroll box to specified position. The current position is specified by the nPos parameter.

nPos
Specifies the scroll-box position if the scroll-bar code is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise, not used. Depending on the initial scroll range, nPos may be negative and should be cast to an int if necessary.

pScrollBar
If the scroll message came from a scroll-bar control, contains a pointer to the control. If the user clicked a window's scroll bar, this parameter is NULL. The pointer may be temporary and should not be stored for later use.

Remarks

The SB_THUMBTRACK scroll-bar code typically is used by applications that give some feedback while the scroll box is being dragged.

If an application scrolls the contents controlled by the scroll bar, it must also reset the position of the scroll box with the SetScrollPos member function.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

The Clipboard owner's OnHScrollClipboard member function is called by the Clipboard viewer when the Clipboard data has the CF_OWNERDISPLAY format and there is an event in the Clipboard viewer's horizontal scroll bar.

Parameters

pClipAppWnd
Specifies a pointer to a Clipboard-viewer window. The pointer may be temporary and should not be stored for later use.

nSBCode
Specifies one of the following scroll-bar codes in the low-order word:

SB_BOTTOM Scroll to lower right.

SB_ENDSCROLL End scroll.

SB_LINEDOWN Scroll one line down.

SB_LINEUP Scroll one line up.

SB_PAGEDOWN Scroll one page down.

SB_PAGEUP Scroll one page up.

SB_THUMBPOSITION Scroll to the absolute position. The current position is provided in nPos.

SB_TOP Scroll to upper left.

nPos
Contains the scroll-box position if the scroll-bar code is SB_THUMBPOSITION; otherwise not used.

Remarks

The owner should scroll the Clipboard image, invalidate the appropriate section, and update the scroll-bar values.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pDC
Specifies the device-context object of the icon. May be temporary and should not be stored for later use.

Remarks

CWnd receives this call only if a class icon is defined for the window default implementation; otherwise OnEraseBkgnd is called.

The DefWindowProc member function fills the icon background with the background brush of the parent window.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pMenu
Specifies the menu to be initialized. May be temporary and should not be stored for later use.

Remarks

OnInitMenu is called when the user clicks an item on the menu bar or presses a menu key. Override this member function to modify the menu before it is displayed.

OnInitMenu is only called once, when a menu is first accessed (for example, when a user clicks an item on the menu bar). This method does not provide information about menu items. As the user moves to items within the menu (for example, by moving the mouse across several menu items) the function is not called again. Once the user exits from the menu (for example, by clicking on the application client area) and later clicks an item on the menu bar, the function will be called again.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pPopupMenu
Specifies the menu object of the pop-up menu. May be temporary and should not be stored for later use.

nIndex
Specifies the index of the pop-up menu in the main menu.

bSysMenuTRUE if the pop-up menu is the Control menu; otherwise FALSE.

Remarks

This allows an application to modify the pop-up menu before it is displayed without changing the entire menu.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

- GIDC_ARRIVAL - A new device has been added to the system.- GIDC_REMOVAL - A device has been removed from the system.

Remarks

This method receives the WM_INPUT_DEVICE_CHANGE notification, which is described in the Windows SDK. The is a generic input device message.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This method receives the WM_INPUTLANGCHANGE notification message, which is described in the Windows SDK.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

Parameter

Description

[in] nFlags

A bitwise (OR) combination of flags that indicate the new locale was selected from the previous or next locale in the installed list of locales, or that the new input locale's keyboard layout can be used with the system character set.

The possible values are INPUTLANGCHANGE_BACKWARD, INPUTLANGCHANGE_FORWARD, and INPUTLANGCHANGE_SYSCHARSET.

Remarks

This method receives the WM_INPUTLANGCHANGEREQUEST notification message, which is described in the Windows SDK. This message is posted when the user chooses a new input language with either a hotkey that is specified in the keyboard control panel application, or from the indicator on the system taskbar.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nChar
Specifies the virtual key code of the given key. For a list of of standard virtual key codes, see Winuser.h

nRepCnt
Repeat count (the number of times the keystroke is repeated as a result of the user holding down the key).

nFlags
Specifies the scan code, key-transition code, previous key state, and context code, as shown in the following list:

Value

Description

0–7

Scan code (OEM-dependent value).

8

Extended key, such as a function key or a key on the numeric keypad (1 if it is an extended key).

9–10

Not used.

11–12

Used internally by Windows.

13

Context code (1 if the ALT key is held down while the key is pressed; otherwise 0).

14

Previous key state (1 if the key is down before the call, 0 if the key is up).

15

Transition state (1 if the key is being released, 0 if the key is being pressed).

For a WM_KEYDOWN message, the key-transition bit (bit 15) is 0 and the context-code bit (bit 13) is 0.

Remarks

A nonsystem key is a keyboard key that is pressed when the ALT key is not pressed or a keyboard key that is pressed when CWnd has the input focus.

Because of auto-repeat, more than one OnKeyDown call may occur before an OnKeyUp member function call is made. The bit that indicates the previous key state can be used to determine whether the OnKeyDown call is the first down transition or a repeated down transition.

For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the slash (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in nFlags.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nChar
Specifies the virtual key code of the given key. For a list of of standard virtual key codes, see Winuser.h

nRepCnt
Repeat count (the number of times the keystroke is repeated as a result of the user holding down the key).

nFlags
Specifies the scan code, key-transition code, previous key state, and context code, as shown in the following list:

Value

Description

0–7

Scan code (OEM-dependent value). Low byte of high-order word.

8

Extended key, such as a function key or a key on the numeric keypad (1 if it is an extended key; otherwise 0).

9–10

Not used.

11–12

Used internally by Windows.

13

Context code (1 if the ALT key is held down while the key is pressed; otherwise 0).

14

Previous key state (1 if the key is down before the call, 0 if the key is up).

15

Transition state (1 if the key is being released, 0 if the key is being pressed).

For a WM_KEYUP message, the key-transition bit (bit 15) is 1 and the context-code bit (bit 13) is 0.

Remarks

A nonsystem key is a keyboard key that is pressed when the ALT key is not pressed or a keyboard key that is pressed when the CWnd has the input focus.

For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to the left of the numeric keypad; and the slash (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in nFlags.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pNewWnd
Specifies a pointer to the window that receives the input focus (may be NULL or may be temporary).

Remarks

If the CWnd object is displaying a caret, the caret should be destroyed at this point.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_LBUTTON Set if the left mouse button is down.

MK_MBUTTON Set if the middle mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

point
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

Remarks

Only windows that have the CS_DBLCLKSWNDCLASS style will receive OnLButtonDblClk calls. This is the default for Microsoft Foundation Class windows. Windows calls OnLButtonDblClk when the user presses, releases, and then presses the left mouse button again within the system's double-click time limit. Double-clicking the left mouse button actually generates four events: WM_LBUTTONDOWN, WM_LBUTTONUP messages, the WM_LBUTTONDBLCLK call, and another WM_LBUTTONUP message when the button is released.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_LBUTTON Set if the left mouse button is down.

MK_MBUTTON Set if the middle mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

point
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_MBUTTON Set if the middle mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

point
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_LBUTTON Set if the left mouse button is down.

MK_MBUTTON Set if the middle mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

point
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

Remarks

Only windows that have the CS_DBLCLKSWNDCLASS style will receive OnMButtonDblClk calls. This is the default for all Microsoft Foundation Class windows. Windows generates an OnMButtonDblClk call when the user presses, releases, and then presses the middle mouse button again within the system's double-click time limit. Double-clicking the middle mouse button actually generates four events: WM_MBUTTONDOWN and WM_MBUTTONUP messages, the WM_MBUTTONDBLCLK call, and another WM_MBUTTONUP message.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_LBUTTON Set if the left mouse button is down.

MK_MBUTTON Set if the middle mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

point
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_LBUTTON Set if the left mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

point
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bActivateTRUE if the child is being activated and FALSE if it is being deactivated.

pActivateWnd
Contains a pointer to the MDI child window to be activated. When received by an MDI child window, pActivateWnd contains a pointer to the child window being activated. This pointer may be temporary and should not be stored for later use.

pDeactivateWnd
Contains a pointer to the MDI child window being deactivated. This pointer may be temporary and should not be stored for later use.

Remarks

An MDI child window is activated independently of the MDI frame window. When the frame becomes active, the child window that was last activated with a OnMDIActivate call receives an WM_NCACTIVATE message to draw an active window frame and caption bar, but it does not receive another OnMDIActivate call.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nIDCtl
The ID of the control.

lpMeasureItemStruct
Points to a MEASUREITEMSTRUCT data structure that contains the dimensions of the owner-draw control.

Remarks

Override this member function and fill in the MEASUREITEMSTRUCT data structure pointed to by lpMeasureItemStruct and return; this informs Windows of the dimensions of the control and allows Windows to process user interaction with the control correctly.

If a list box or combo box is created with the LBS_OWNERDRAWVARIABLE or CBS_OWNERDRAWVARIABLE style, the framework calls this function for the owner for each item in the control; otherwise this function is called once.

Windows initiates the call to OnMeasureItem for the owner of combo boxes and list boxes created with the OWNERDRAWFIXED style before sending the WM_INITDIALOG message. As a result, when the owner receives this call, Windows has not yet determined the height and width of the font used in the control; function calls and calculations that require these values should occur in the main function of the application or library.

If the item being measured is a CMenu, CListBox or CComboBox object, then the MeasureItem virtual function of the appropriate class is called. Override the MeasureItem member function of the appropriate control's class to calculate and set the size of each item.

OnMeasureItem will be called only if the control's class is created at run time, or it is created with the LBS_OWNERDRAWVARIABLE or CBS_OWNERDRAWVARIABLE style. If the control is created by the dialog editor, OnMeasureItem will not be called. This is because the WM_MEASUREITEM message is sent early in the creation process of the control. If you subclass by using DDX_Control, SubclassDlgItem, or SubclassWindow, the subclassing usually occurs after the creation process. Therefore, there is no way to handle the WM_MEASUREITEM message in the control's OnChildNotify function, which is the mechanism MFC uses to implement ON_WM_MEASUREITEM_REFLECT.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nChar
Depending on the build settings, specifies the ANSI or Unicode character that the user pressed.

nFlags
Contains the MF_POPUP flag if the menu is a pop-up menu. It contains the MF_SYSMENU flag if the menu is a Control menu.

pMenu
Contains a pointer to the selected CMenu. The pointer may be temporary and should not be stored.

Return Value

The high-order word of the return value should contain one of the following command codes:

Value

Description

0

Tells Windows to discard the character that the user pressed and creates a short beep on the system speaker.

1

Tells Windows to close the current menu.

2

Informs Windows that the low-order word of the return value contains the item number for a specific item. This item is selected by Windows.

The low-order word is ignored if the high-order word contains 0 or 1. Applications should process this message when accelerator (shortcut) keys are used to select bitmaps placed in a menu.

Remarks

It is sent to the CWnd that owns the menu. OnMenuChar is also called when the user presses ALT and any other key, even if the key does not correspond to a mnemonic character. In this case, pMenu points to the menu owned by the CWnd, and nFlags is 0.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Return Value

The menu should remain active. If the mouse is released, it should be ignored.

MND_ENDMENU

The menu should be ended.

Remarks

This method receives the WM_MENUDRAG notification, which is described in the Windows SDK.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

Pointer to a MENUGETOBJECTINFO structure that contains information about the drag-and-drop menu the mouse cursor is on.

Return Value

Return Value

Meaning

MNGO_NOERROR

An interface pointer that supports drop-and-drag operations is returned in the pvObj member of the MENUGETOBJECTINFO structure. Currently, only the IDropTarget interface is supported.

MNGO_NOINTERFACE

No drop-and-drag interface is supported.

Remarks

This method receives the WM_MENUGETOBJECT notification, which is described in the Windows SDK.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

Remarks

This method receives the WM_MENURBUTTONUP notification, which is described in the Windows SDK. The WM_MENURBUTTONUP message enables an application to provide a context-sensitive menu for the menu item specified in the message.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nItemID
Identifies the item selected. If the selected item is a menu item, nItemID contains the menu-item ID. If the selected item contains a pop-up menu, nItemID contains the pop-up menu index, and hSysMenu contains the handle of the main (clicked-on) menu.

nFlags
Contains a combination of the following menu flags:

MF_BITMAP Item is a bitmap.

MF_CHECKED Item is checked.

MF_DISABLED Item is disabled.

MF_GRAYED Item is dimmed.

MF_MOUSESELECT Item was selected with a mouse.

MF_OWNERDRAW Item is an owner-draw item.

MF_POPUP Item contains a pop-up menu.

MF_SEPARATOR Item is a menu-item separator.

MF_SYSMENU Item is contained in the Control menu.

hSysMenu
If nFlags contains MF_SYSMENU, identifies the menu associated with the message. If nFlags contains MF_POPUP, identifies the handle of the main menu. If nFlags contains neither MF_SYSMENU nor MF_POPUP, it is unused.

Remarks

If nFlags contains 0xFFFF and hSysMenu contains 0, Windows has closed the menu because the user pressed the ESC key or clicked outside the menu.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

pDesktopWnd
Specifies a pointer to the top-level parent window of the window being activated. The pointer may be temporary and should not be stored.

nHitTest
Specifies the hit-test area code. A hit test is a test that determines the location of the cursor.

message
Specifies the mouse message number.

Return Value

Specifies whether to activate the CWnd and whether to discard the mouse event. It must be one of the following values:

MA_ACTIVATE Activate CWnd object.

MA_NOACTIVATE Do not activate CWnd object.

MA_ACTIVATEANDEAT Activate CWnd object and discard the mouse event.

MA_NOACTIVATEANDEAT Do not activate CWnd object and discard the mouse event.

Remarks

The default implementation passes this message to the parent window before any processing occurs. If the parent window returns TRUE, processing is halted.

For a description of the individual hit-test area codes, see the OnNcHitTest member function

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

A bitwise combination (OR) of flags that indicate which modifier keys are pressed. For example, the MK_CONTROL flag indicates that the CTRL key is pressed.

[in] point

A CPoint object that specifies the x and y coordinates of the cursor relative to the upper-left corner of the client area.

Remarks

This method receives the WM_MOUSEHOVER notification, which is described in the Windows SDK.

The nFlags parameter can be a combination of modifier keys listed in the following table. For more information, see About Mouse Input.

Modifier Key

Description

MK_CONTROL

The CTRL key is pressed.

MK_LBUTTON

The left mouse button is pressed.

MK_MBUTTON

The middle mouse button is pressed.

MK_RBUTTON

The right mouse button is pressed.

MK_SHIFT

The SHIFT key is pressed.

MK_XBUTTON1

The XBUTTON1 mouse button of the Microsoft IntelliMouse is pressed.

MK_XBUTTON2

The XBUTTON2 mouse button of the Microsoft IntelliMouse is pressed.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Indicates the distance the wheel is rotated, expressed in multiples or divisions of WHEEL_DELTA, which is 120. A positive value indicates that the wheel was rotated to the right; a negative value indicates that the wheel was rotated to the left.

[in] pt

A CPoint object that specifies the x and y coordinates of the cursor relative to the upper-left corner of the client area.

Remarks

This method receives the WM_MOUSEHWHEEL notification message, which is described in the Windows SDK. This message is sent to the window that has the focus when the mouse's horizontal scroll wheel is tilted or rotated.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This method receives the WM_MOUSELEAVE notification, which is described in the Windows SDK.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_LBUTTON Set if the left mouse button is down.

MK_MBUTTON Set if the middle mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

point
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the window.

Remarks

If the mouse is not captured, the WM_MOUSEMOVE message is received by the CWnd object beneath the mouse cursor; otherwise, the message goes to the window that has captured the mouse.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nFlags
Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

MK_CONTROL Set if the CTRL key is down.

MK_LBUTTON Set if the left mouse button is down.

MK_MBUTTON Set if the middle mouse button is down.

MK_RBUTTON Set if the right mouse button is down.

MK_SHIFT Set if the SHIFT key is down.

zDelta
Indicates distance rotated. The zDelta value is expressed in multiples or divisions of WHEEL_DELTA, which is 120. A value less than zero indicates rotating back (toward the user) while a value greater than zero indicates rotating forward (away from the user). The user can reverse this response by changing the Wheel setting in the mouse software. See the Remarks for more information about this parameter.

pt
Specifies the x- and y-coordinate of the cursor. These coordinates are always relative to the upper-left corner of the screen.

Return Value

Nonzero if mouse wheel scrolling is enabled; otherwise 0.

Remarks

Unless overridden, OnMouseWheel calls the default of WM_MOUSEWHEEL. Windows automatically routes the message to the control or child window that has the focus. The Win32 function DefWindowProc propagates the message up the parent chain to the window that processes it.

The zDelta parameter is a multiple of WHEEL_DELTA, which is set at 120. This value is the threshold for an action to be taken, and one such action (for example, scrolling forward one notch) should occur for each delta.

WHEEL_DELTA was set to 120 to allow for finer-resolution wheels, such as a freely-rotating wheel with no notches. A finer-resolution wheel sends more messages per rotation, but each message has a smaller delta value. To use such a wheel, either add the incoming zDelta values until WHEEL_DELTA is reached (so that you get the same response for a given delta-rotation), or scroll partial lines in response to the more frequent messages. You can also choose a scroll granularity and accumulate deltas until WHEEL_DELTA is reached.

Override this member function to provide your own mouse-wheel scrolling behavior.

Parameters

x
Specifies the new x-coordinate location of the upper-left corner of the client area. This new location is given in screen coordinates for overlapped and pop-up windows, and parent-client coordinates for child windows.

y
Specifies the new y-coordinate location of the upper-left corner of the client area. This new location is given in screen coordinates for overlapped and pop-up windows, and parent-client coordinates for child windows.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bActive
Specifies when a caption bar or icon needs to be changed to indicate an active or inactive state. The bActive parameter is TRUE if an active caption or icon is to be drawn. It is FALSE for an inactive caption or icon.

Return Value

Nonzero if Windows should proceed with default processing; 0 to prevent the caption bar or icon from being deactivated.

Remarks

The default implementation draws the title bar and title-bar text in their active colors if bActive is TRUE and in their inactive colors if bActive is FALSE.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

bCalcValidRects
Specifies whether the application should specify which part of the client area contains valid information. Windows will copy the valid information to the specified area within the new client area. If this parameter is TRUE, the application should specify which part of the client area is valid.

lpncsp
Points to a NCCALCSIZE_PARAMS data structure that contains information an application can use to calculate the new size and position of the CWnd rectangle (including client area, borders, caption, scroll bars, and so on).

Remarks

By processing this message, an application can control the contents of the window's client area when the size or position of the window changes.

Regardless of the value of bCalcValidRects, the first rectangle in the array specified by the rgrc structure member of the NCCALCSIZE_PARAMS structure contains the coordinates of the window. For a child window, the coordinates are relative to the parent window's client area. For top-level windows, the coordinates are screen coordinates. An application should modify the rgrc[0] rectangle to reflect the size and position of the client area.

The rgrc[1] and rgrc[2] rectangles are valid only if bCalcValidRects is TRUE. In this case, the rgrc[1] rectangle contains the coordinates of the window before it was moved or resized. The rgrc[2] rectangle contains the coordinates of the window's client area before the window was moved. All coordinates are relative to the parent window or screen.

The default implementation calculates the size of the client area based on the window characteristics (presence of scroll bars, menu, and so on), and places the result in lpncsp.

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

Return Value

Nonzero if the nonclient area is created. It is 0 if an error occurs; the Create function will return failure in this case.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

The default implementation performs some cleanup, then calls the virtual member function PostNcDestroy.

Override PostNcDestroy if you want to perform your own cleanup, such as a delete this operation. If you override OnNcDestroy, you must call OnNcDestroy in your base class to ensure that any memory internally allocated for the window is freed.

The framework calls this member function for the CWnd object that contains the cursor (or the CWnd object that used the SetCapture member function to capture the mouse input) every time the mouse is moved.

Parameters

point
Contains the x- and y-coordinates of the cursor. These coordinates are always screen coordinates.

Return Value

One of the mouse hit-test enumerated values listed below.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received.If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Remarks

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nHitTest
Specifies the hit-test code. A hit test is a test that determines the location of the cursor.

point
Specifies a CPoint object that contains the x and y screen coordinates of the cursor position. These coordinates are always relative to the upper-left corner of the screen.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nHitTest
Specifies the hit-test code. A hit test is a test that determines the location of the cursor.

point
Specifies a CPoint object that contains the x and y screen coordinates of the cursor position. These coordinates are always relative to the upper-left corner of the screen.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.

Parameters

nHitTest
Specifies the hit-test code. A hit test is a test that determines the location of the cursor.

point
Specifies a CPoint object that contains the x and y screen coordinates of the cursor position. These coordinates are always relative to the upper-left corner of the screen.

Remarks

Note

This member function is called by the framework to allow your application to handle a Windows message. The parameters passed to your function reflect the parameters received by the framework when the message was received. If you call the base-class implementation of this function, that implementation will use the parameters originally passed with the message and not the parameters you supply to the function.