CWnd Class

 

Provides the base functionality of all window classes in the Microsoft Foundation Class Library.

class CWnd : public CCmdTarget  

Public Constructors

NameDescription
CWnd::CWndConstructs a CWnd object.

Public Methods

NameDescription
CWnd::accDoDefaultActionCalled by the framework to perform the object's default action.
CWnd::accHitTestCalled by the framework to retrieve the child element or child object at a given point on the screen.
CWnd::accLocationCalled by the framework to retrieve the specified object's current screen location.
CWnd::accNavigateCalled by the framework to traverse to another user interface element within a container and if possible, retrieve the object.
CWnd::accSelectCalled by the framework to modify the selection or move the keyboard focus of the specified object.
CWnd::AnimateWindowAnimates the associated window object.
CWnd::ArrangeIconicWindowsArranges all the minimized (iconic) child windows.
CWnd::AttachAttaches a Windows handle to a CWnd object.
CWnd::BeginModalStateCall this member function to make a frame window modal.
CWnd::BeginPaintPrepares CWnd for painting.
CWnd::BindDefaultPropertyBinds the calling object's default simple bound property, as marked in the type library, to a cursor associated with a data-source control.
CWnd::BindPropertyBinds a cursor-bound property on a data-bound control to a data-source control and registers that relationship with the MFC binding manager.
CWnd::BringWindowToTopBrings CWnd to the top of a stack of overlapping windows.
CWnd::CalcWindowRectCalled to calculate the window rectangle from the client rectangle.
CWnd::CancelToolTipsDisables the tooltip control.
CWnd::CenterWindowCenters a window relative to its parent.
CWnd::ChangeClipboardChainRemoves CWnd from the chain of Clipboard viewers.
CWnd::CheckDlgButtonPlaces a check mark next to or removes a check mark from a button control.
CWnd::CheckRadioButtonChecks the specified radio button and removes the check mark from all other radio buttons in the specified group of buttons.
CWnd::ChildWindowFromPointDetermines which, if any, of the child windows contains the specified point.
CWnd::ClientToScreenConverts the client coordinates of a given point or rectangle on the display to screen coordinates.
CWnd::CloseWindowMinimizes the window.
CWnd::ContinueModalContinues a window's modal status.
CWnd::CreateCreates and initializes the child window associated with the CWnd object.
CWnd::CreateAccessibleProxyCreates an Active Accessibility proxy for the specified object.
CWnd::CreateCaretCreates a new shape for the system caret and gets ownership of the caret.
CWnd::CreateControlCreate an ActiveX control that will be represented in an MFC program by a CWnd object.
CWnd::CreateExCreates a Windows overlapped, pop-up, or child window and attaches it to a CWnd object.
CWnd::CreateGrayCaretCreates a gray block for the system caret and gets ownership of the caret.
CWnd::CreateSolidCaretCreates a solid block for the system caret and gets ownership of the caret.
CWnd::DeleteTempMapCalled automatically by the CWinApp idle-time handler and deletes any temporary CWnd objects created by FromHandle.
CWnd::DestroyWindowDestroys the attached Windows window.
CWnd::DetachDetaches a Windows handle from a CWnd object and returns the handle.
CWnd::DlgDirListFills a list box with a file or directory listing.
CWnd::DlgDirListComboBoxFills the list box of a combo box with a file or directory listing.
CWnd::DlgDirSelectRetrieves the current selection from a list box.
CWnd::DlgDirSelectComboBoxRetrieves the current selection from the list box of a combo box.
CWnd::DragAcceptFilesIndicates the window will accept dragged files.
CWnd::DragDetectCaptures 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.
CWnd::DrawAnimatedRectsDraws a wire-frame rectangle and animates it to indicate the opening of an icon or the minimizing or maximizing of a window.
CWnd::DrawCaptionDraws a caption.
CWnd::DrawMenuBarRedraws the menu bar.
CWnd::EnableActiveAccessibilityEnables user-defined Active Accessibility functions.
CWnd::EnableDynamicLayoutEnables the position and size of child windows to adjust dynamically when the user resizes the window.
CWnd::EnableD2DSupportEnables or disables window D2D support. Call this method before the main window is initialized.
CWnd::EnableScrollBarEnables or disables one or both arrows of a scroll bar.
CWnd::EnableScrollBarCtrlEnables or disables a sibling scroll-bar control.
CWnd::EnableToolTipsEnables the tooltip control.
CWnd::EnableTrackingToolTipsEnables the tooltip control in tracking mode.
CWnd::EnableWindowEnables or disables mouse and keyboard input.
CWnd::EndModalLoopEnds a window's modal status.
CWnd::EndModalStateCall this member function to change a frame window from modal to modeless.
CWnd::EndPaintMarks the end of painting.
CWnd::ExecuteDlgInitInitiates a dialog resource.
CWnd::FilterToolTipMessageRetrieves the title or text associated with a control in a dialog box.
CWnd::FindWindowReturns the handle of the window, which is identified by its window name and window class.
CWnd::FindWindowExReturns the handle of the window, which is identified by its window name and window class.
CWnd::FlashWindowFlashes the window once.
CWnd::FlashWindowExFlashes the window with additional functionality.
CWnd::FromHandleReturns a pointer to a CWnd object when given a handle to a window. If a CWnd object is not attached to the handle, a temporary CWnd object is created and attached.
CWnd::FromHandlePermanentReturns a pointer to a CWnd object when given a handle to a window. If a CWnd object is not attached to the handle, a temporary CWnd object is created and attached.
CWnd::get_accChildCalled by the framework to retrieve the address of an IDispatch interface for the specified child.
CWnd::get_accChildCountCalled by the framework to retrieve the number of children belonging to this object.
CWnd::get_accDefaultActionCalled by the framework to retrieve a string that describes the object's default action.
CWnd::get_accDescriptionCalled by framework to retrieve a string that describes the visual appearance of the specified object.
CWnd::get_accFocusCalled by the framework to retrieve the object that has the keyboard focus.
CWnd::get_accHelpCalled by the framework to retrieve an object's Help property string.
CWnd::get_accHelpTopicCalled by the framework to retrieve the full path of the WinHelp file associated with the specified object and the identifier of the appropriate topic within that file.
CWnd::get_accKeyboardShortcutCalled by the framework to retrieve the specified object's shortcut key or access key.
CWnd::get_accNameCalled by the framework to retrieve the name of the specified object.
CWnd::get_accParentCalled by the framework to retrieve the IDispatch interface of the object's parent.
CWnd::get_accRoleCalled by the framework to retrieve information that describes the role of the specified object.
CWnd::get_accSelectionCalled by the framework to retrieve the selected children of this object.
CWnd::get_accStateCalled by the framework to retrieve the current state of the specified object.
CWnd::get_accValueCalled by the framework to retrieve the value of the specified object.
CWnd::GetActiveWindowRetrieves the active window.
CWnd::GetAncestorRetrieves the ancestor window object of the specified window.
CWnd::GetCaptureRetrieves the CWnd that has the mouse capture.
CWnd::GetCaretPosRetrieves the client coordinates of the caret's current position.
CWnd::GetCheckedRadioButtonReturns the ID of the currently checked radio button in a group of buttons.
CWnd::GetClientRectGets the dimensions of the CWnd client area.
CWnd::GetClipboardOwnerRetrieves a pointer to the current owner of the Clipboard.
CWnd::GetClipboardViewerRetrieves a pointer to the first window in the chain of Clipboard viewers.
CWnd::GetControlUnknownRetrieves a pointer to an unknown ActiveX control.
CWnd::GetDCRetrieves a display context for the client area.
CWnd::GetDCExRetrieves a display context for the client area, and enables clipping while drawing.
CWnd::GetDCRenderTargetRetrieves the device context (DC) render target for the CWnd window.
CWnd::GetDescendantWindowSearches all descendant windows and returns the window with the specified ID.
CWnd::GetDesktopWindowRetrieves the Windows desktop window.
CWnd::GetDlgCtrlIDIf the CWnd is a child window, calling this function returns its ID value.
CWnd::GetDlgItemRetrieves the control with the specified ID from the specified dialog box.
CWnd::GetDlgItemIntTranslates the text of a control in the given dialog box to an integer value.
CWnd::GetDlgItemTextRetrieves the caption or text associated with a control.
CWnd::GetDSCCursorRetrieves a pointer to the underlying cursor that is defined by the DataSource, UserName, Password, and SQL properties of a data-source control.
CWnd::GetDynamicLayoutRetrieves a pointer to the dynamic layout manager object.
CWnd::GetExStyleReturns the window's extended style.
CWnd::GetFocusRetrieves the CWnd that currently has the input focus.
CWnd::GetFontRetrieves the current font.
CWnd::GetForegroundWindowReturns a pointer to the foreground window (the top-level window with which the user is currently working).
CWnd::GetIconRetrieves the handle to an icon.
CWnd::GetLastActivePopupDetermines which pop-up window owned by CWnd was most recently active.
CWnd::GetLayeredWindowAttributesRetrieves the opacity and transparency color key of a layered window.
CWnd::GetMenuRetrieves a pointer to the specified menu.
CWnd::GetNextDlgGroupItemSearches for the next (or previous) control within a group of controls.
CWnd::GetNextDlgTabItemRetrieves the first control with the WS_TABSTOP style that follows (or precedes) the specified control.
CWnd::GetNextWindowReturns the next (or previous) window in the window manager's list.
CWnd::GetOleControlSiteRetrieves the custom site for the specified ActiveX control.
CWnd::GetOpenClipboardWindowRetrieves a pointer to the window that currently has the Clipboard open.
CWnd::GetOwnerRetrieves a pointer to the owner of a CWnd.
CWnd::GetParentRetrieves the parent window of CWnd (if any).
CWnd::GetParentFrameRetrieves the CWnd object's parent frame window.
CWnd::GetParentOwnerReturns a pointer to a child window's parent window.
CWnd::GetPropertyRetrieves an ActiveX control property.
CWnd::GetRenderTargetGets a render target that is associated with this window.
CWnd::GetSafeHwndReturns m_hWnd, or NULL if the this pointer is NULL.
CWnd::GetSafeOwnerRetrieves the safe owner for the given window.
CWnd::GetScrollBarCtrlReturns a sibling scroll-bar control.
CWnd::GetScrollBarInfoRetrieves information about the specified scroll bar.
CWnd::GetScrollInfoRetrieves the information that the SCROLLINFO structure maintains about a scroll bar.
CWnd::GetScrollLimitRetrieves the limit of the scroll bar.
CWnd::GetScrollPosRetrieves the current position of a scroll box.
CWnd::GetScrollRangeCopies the current minimum and maximum scroll-bar positions for the given scroll bar.
CWnd::GetStyleReturns the current window style.
CWnd::GetSystemMenuAllows the application to access the Control menu for copying and modification.
CWnd::GetTitleBarInfoRetrieves information about the specified title bar.
CWnd::GetTopLevelFrameRetrieves the window's top-level frame window.
CWnd::GetTopLevelOwnerRetrieves the top-level window.
CWnd::GetTopLevelParentRetrieves the window's top-level parent.
CWnd::GetTopWindowReturns the first child window that belongs to the CWnd.
CWnd::GetUpdateRectRetrieves the coordinates of the smallest rectangle that completely encloses the CWnd update region.
CWnd::GetUpdateRgnRetrieves the CWnd update region.
CWnd::GetWindowReturns the window with the specified relationship to this window.
CWnd::GetWindowContextHelpIdRetrieves the help context identifier.
CWnd::GetWindowDCRetrieves the display context for the whole window, including the caption bar, menus, and scroll bars.
CWnd::GetWindowedChildCountReturns the number of associated child windows.
CWnd::GetWindowInfoReturns information about the window.
CWnd::GetWindowlessChildCountReturns the number of associated windowless child windows.
CWnd::GetWindowPlacementRetrieves the show state and the normal (restored), minimized, and maximized positions of a window.
CWnd::GetWindowRectGets the screen coordinates of CWnd.
CWnd::GetWindowRgnRetrieves a copy of the window region of a window.
CWnd::GetWindowTextReturns the window text or caption title (if it has one).
CWnd::GetWindowTextLengthReturns the length of the window's text or caption title.
CWnd::HideCaretHides the caret by removing it from the display screen.
CWnd::HiliteMenuItemHighlights or removes the highlighting from a top-level (menu-bar) menu item.
CWnd::HtmlHelpCalled to initiate the HTMLHelp application.
CWnd::InvalidateInvalidates the entire client area.
CWnd::InvalidateRectInvalidates the client area within the given rectangle by adding that rectangle to the current update region.
CWnd::InvalidateRgnInvalidates the client area within the given region by adding that region to the current update region.
CWnd::InvokeHelperInvokes an ActiveX control method or property.
CWnd::IsChildIndicates whether CWnd is a child window or other direct descendant of the specified window.
CWnd::IsD2DSupportEnabledDetermines whether D2D support is enabled.
CWnd::IsDialogMessageDetermines whether the given message is intended for the modeless dialog box and, if so, processes it.
CWnd::IsDlgButtonCheckedDetermines whether a button control is checked.
CWnd::IsDynamicLayoutEnabledDetermines whether dynamic layout is enabled on this window. If dynamic layout is enabled, the position and size of child windows can change when the user resizes the parent window.
CWnd::IsIconicDetermines whether CWnd is minimized (iconic).
CWnd::IsTouchWindowSpecifies whether CWnd has touch support.
CWnd::IsWindowEnabledDetermines whether the window is enabled for mouse and keyboard input.
CWnd::IsWindowVisibleDetermines whether the window is visible.
CWnd::IsZoomedDetermines whether CWnd is maximized.
CWnd::KillTimerKills a system timer.
CWnd::LockWindowUpdateDisables or reenables drawing in the given window.
CWnd::MapWindowPointsConverts (maps) a set of points from the coordinate space of the CWnd to the coordinate space of another window.
CWnd::MessageBoxCreates and displays a window that contains an application-supplied message and caption.
CWnd::ModifyStyleModifies the current window style.
CWnd::ModifyStyleExModifies the window's extended style.
CWnd::MoveWindowChanges the position and dimensions of CWnd.
CWnd::NotifyWinEventSignals the system that a predefined event occurred.
CWnd::OnAmbientPropertyImplement ambient property values.
CWnd::OnDrawIconicThumbnailOrLivePreviewCalled by the framework when it needs to obtain a bitmap to be displayed on Windows 7 tab thumbnail, or on the client for application peek.
CWnd::OnHelpHandles F1 Help within the application (using the current context).
CWnd::OnHelpFinderHandles the ID_HELP_FINDER and ID_DEFAULT_HELP commands.
CWnd::OnHelpIndexHandles the ID_HELP_INDEX command and provides a default Help topic.
CWnd::OnHelpUsingHandles the ID_HELP_USING command.
CWnd::OnToolHitTestDetermines whether a point is in the bounding rectangle of the specified tool and retrieves information about the tool.
CWnd::OpenClipboardOpens the Clipboard. Other applications will not be able to modify the Clipboard until the Windows CloseClipboard function is called.
CWnd::PaintWindowlessControlsDraws windowless controls on the control container.
CWnd::PostMessagePlaces a message in the application queue, then returns without waiting for the window to process the message.
CWnd::PreCreateWindowCalled before the creation of the Windows window attached to this CWnd object.
CWnd::PreSubclassWindowAllows other necessary subclassing to occur before SubclassWindow is called.
CWnd::PreTranslateMessageUsed by CWinApp to filter window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions.
CWnd::PrintDraws the current window in the specified device context.
CWnd::PrintClientDraws any window in the specified device context (usually a printer device context).
CWnd::PrintWindowCopies a visual window into the specified device context, typically a printer DC.
CWnd::RedrawWindowUpdates the specified rectangle or region in the client area.
CWnd::RegisterTouchWindowRegister/Unregister window Windows touch support.
CWnd::ReleaseDCReleases client and window device contexts, freeing them for use by other applications.
CWnd::RepositionBarsRepositions control bars in the client area.
CWnd::RunModalLoopRetrieves, translates, or dispatches messages for a window that is in modal status.
CWnd::ScreenToClientConverts the screen coordinates of a given point or rectangle on the display to client coordinates.
CWnd::ScrollWindowScrolls the contents of the client area.
CWnd::ScrollWindowExScrolls the contents of the client area. Similar to ScrollWindow, with additional features.
CWnd::SendChildNotifyLastMsgProvides a notification message to a child window, from the parent window, so the child window can handle a task.
CWnd::SendDlgItemMessageSends a message to the specified control.
CWnd::SendMessageSends a message to the CWnd object and does not return until it has processed the message.
CWnd::SendMessageToDescendantsSends a message to all descendant windows of the window.
CWnd::SendNotifyMessageSends the specified message to the window and returns as soon as possible, depending on whether the calling thread created the window.
CWnd::SetActiveWindowActivates the window.
CWnd::SetCaptureCauses all subsequent mouse input to be sent to the CWnd.
CWnd::SetCaretPosMoves the caret to a specified position.
CWnd::SetClipboardViewerAdds CWnd to the chain of windows that are notified whenever the contents of the Clipboard are changed.
CWnd::SetDlgCtrlIDSets the window or control ID for the window (which can be any child window, not only a control in a dialog box).
CWnd::SetDlgItemIntSets the text of a control to the string that represents an integer value.
CWnd::SetDlgItemTextSets the caption or text of a control in the specified dialog box.
CWnd::SetFocusClaims the input focus.
CWnd::SetFontSets the current font.
CWnd::SetForegroundWindowPuts the thread that created the window into the foreground and activates the window.
CWnd::SetIconSets the handle to a specific icon.
CWnd::SetLayeredWindowAttributesSets the opacity and transparency color key of a layered window.
CWnd::SetMenuSets the menu to the specified menu.
CWnd::SetOwnerChanges the owner of a CWnd.
CWnd::SetParentChanges the parent window.
CWnd::SetPropertySets an ActiveX control property.
CWnd::SetRedrawAllows changes in CWnd to be redrawn or prevents changes from being redrawn.
CWnd::SetScrollInfoSets information about the scroll bar.
CWnd::SetScrollPosSets the current position of a scroll box and, if specified, redraws the scroll bar to reflect the new position.
CWnd::SetScrollRangeSets minimum and maximum position values for the given scroll bar.
CWnd::SetTimerInstalls a system timer that sends a WM_TIMER message when triggered.
CWnd::SetWindowContextHelpIdSets the help context identifier.
CWnd::SetWindowPlacementSets the show state and the normal (restored), minimized, and maximized positions for a window.
CWnd::SetWindowPosChanges the size, position, and ordering of child, pop-up, and top-level windows.
CWnd::SetWindowRgnSets the region of a window.
CWnd::SetWindowTextSets the window text or caption title (if it has one) to the specified text.
CWnd::ShowCaretShows the caret on the display at the caret's current position. Once shown, the caret begins flashing automatically.
CWnd::ShowOwnedPopupsShows or hides all pop-up windows owned by the window.
CWnd::ShowScrollBarDisplays or hides a scroll bar.
CWnd::ShowWindowShows or hides the window.
CWnd::SubclassDlgItemAttaches a Windows control to a CWnd object and makes it route messages through the CWnd's message map.
CWnd::SubclassWindowAttaches a window to a CWnd object and makes it route messages through the CWnd's message map.
CWnd::UnlockWindowUpdateUnlocks a window that was locked with CWnd::LockWindowUpdate.
CWnd::UnsubclassWindowDetaches a window from a CWnd object
CWnd::UpdateDataInitializes or retrieves data from a dialog box.
CWnd::UpdateDialogControlsCall to update the state of dialog buttons and other controls.
CWnd::UpdateLayeredWindowUpdates the position, size, shape, content, and translucency of a layered window.
CWnd::UpdateWindowUpdates the client area.
CWnd::ValidateRectValidates the client area within the given rectangle by removing the rectangle from the current update region.
CWnd::ValidateRgnValidates the client area within the given region by removing the region from the current update region.
CWnd::WindowFromPointIdentifies the window that contains the given point.
CWnd::WinHelpCalled to initiate the WinHelp application.

Protected Methods

NameDescription
CWnd::DefaultCalls the default window procedure, which provides default processing for any window messages that an application does not process.
CWnd::DefWindowProcCalls the default window procedure, which provides default processing for any window messages that an application does not process.
CWnd::DoDataExchangeFor dialog data exchange and validation. Called by UpdateData.
CWnd::GetCurrentMessageReturns a pointer to the message this window is currently processing. Should only be called when in an OnMessage message-handler member function.
CWnd::InitDynamicLayoutCalled by the framework to initialize the dynamic layout for the window.
CWnd::LoadDynamicLayoutResourceLoads dynamic layout information from the resource file.
CWnd::OnActivateCalled when CWnd is being activated or deactivated.
CWnd::OnActivateAppCalled when the application is about to be activated or deactivated.
CWnd::OnAppCommandCalled when the user generates an application command event.
CWnd::OnAskCbFormatNameCalled by a Clipboard viewer application when a Clipboard owner will display the Clipboard contents.
CWnd::OnCancelModeCalled to allow CWnd to cancel any internal modes, such as mouse capture.
CWnd::OnCaptureChangedSends a message to the window that is losing the mouse capture.
CWnd::OnChangeCbChainNotifies that a specified window is being removed from the chain.
CWnd::OnChangeUIStateCalled when the user interface (UI) state should be changed.
CWnd::OnCharCalled when a keystroke translates to a non-system character.
CWnd::OnCharToItemCalled by a child list box with the LBS_WANTKEYBOARDINPUT style in response to a WM_CHAR message.
CWnd::OnChildActivateCalled for multiple document interface (MDI) child windows whenever the size or position of CWnd changes or CWnd is activated.
CWnd::OnChildNotifyCalled by a parent window to give a notifying control a chance to respond to a control notification.
CWnd::OnClipboardUpdateCalled when the contents of the clipboard have changed.
CWnd::OnCloseCalled as a signal that CWnd should be closed.
CWnd::OnColorizationColorChangedCalled when the rendering policy for the non-client area has changed.
CWnd::OnCommandCalled when the user selects a command.
CWnd::OnCompactingCalled when Windows detects that system memory is low.
CWnd::OnCompareItemCalled to determine the relative position of a new item in a child sorted owner-draw combo box or list box.
CWnd::OnCompositionChangedCalled for all top-level windows when the Desktop Window Manager (DWM) composition is enabled or disabled.
CWnd::OnContextMenuCalled when the user clicks the right mouse button in the window.
CWnd::OnCopyDataCopies data from one application to another.
CWnd::OnCreateCalled as a part of window creation.
CWnd::OnCtlColorCalled if CWnd is the parent of a control when the control is about to be drawn.
CWnd::OnDeadCharCalled when a keystroke translates to a nonsystem dead character (such as accent characters).
CWnd::OnDeleteItemCalled when an owner-draw child list box or combo box is destroyed or when items are removed from the control.
CWnd::OnDestroyCalled when CWnd is being destroyed.
CWnd::OnDestroyClipboardCalled when the Clipboard is emptied through a call to the Windows EmptyClipboard function.
CWnd::OnDeviceChangeNotifies an application or device driver of a change to the hardware configuration of a device or the computer.
CWnd::OnDevModeChangeCalled for all top-level windows when the user changes device-mode settings.
CWnd::OnDrawClipboardCalled when the contents of the Clipboard change.
CWnd::OnDrawItemCalled when a visual aspect of an owner-draw child button control, combo-box control, list-box control, or menu needs to be drawn.
CWnd::OnDropFilesCalled when the user releases the left mouse button over a window that has registered itself as the recipient of dropped files.
CWnd::OnEnableCalled when CWnd is enabled or disabled.
CWnd::OnEndSessionCalled when the session is ending.
CWnd::OnEnterIdleCalled to inform an application's main window procedure that a modal dialog box or a menu is entering an idle state.
CWnd::OnEnterMenuLoopCalled when a menu modal loop has been entered.
CWnd::OnEnterSizeMoveCalled after the affected window enters a moving or sizing modal loop.
CWnd::OnEraseBkgndCalled when the window background needs erasing.
CWnd::OnExitMenuLoopCalled when a menu modal loop has been exited.
CWnd::OnExitSizeMoveCalled after the affected window exits a moving or sizing modal loop.
CWnd::OnFontChangeCalled when the pool of font resources changes.
CWnd::OnGetDlgCodeCalled for a control so the control can process arrow-key and TAB-key input itself.
CWnd::OnGetMinMaxInfoCalled whenever Windows needs to know the maximized position or dimensions, or the minimum or maximum tracking size.
CWnd::OnHelpInfoCalled by the framework when the user presses the F1 key.
CWnd::OnHotKeyCalled when the user presses a system-wide hot key.
CWnd::OnHScrollCalled when the user clicks the horizontal scroll bar of CWnd.
CWnd::OnHScrollClipboardCalled when a Clipboard owner should scroll the Clipboard image, invalidate the appropriate section, and update the scroll-bar values.
CWnd::OnIconEraseBkgndCalled when CWnd is minimized (iconic) and the background of the icon must be filled before painting the icon.
CWnd::OnInitMenuCalled when a menu is about to become active.
CWnd::OnInitMenuPopupCalled when a pop-up menu is about to become active.
CWnd::OnInputDeviceChangeCalled when an I/O device is added or removed from the system.
CWnd::OnInputLangChangeCalled after an application's input language has been changed.
CWnd::OnInputLangChangeRequestCalled when the user chooses a new input language.
CWnd::OnKeyDownCalled when a nonsystem key is pressed.
CWnd::OnKeyUpCalled when a nonsystem key is released.
CWnd::OnKillFocusCalled immediately before CWnd loses the input focus.
CWnd::OnLButtonDblClkCalled when the user double-clicks the left mouse button.
CWnd::OnLButtonDownCalled when the user presses the left mouse button.
CWnd::OnLButtonUpCalled when the user releases the left mouse button.
CWnd::OnMButtonDblClkCalled when the user double-clicks the middle mouse button.
CWnd::OnMButtonDownCalled when the user presses the middle mouse button.
CWnd::OnMButtonUpCalled when the user releases the middle mouse button.
CWnd::OnMDIActivateCalled when an MDI child window is activated or deactivated.
CWnd::OnMeasureItemCalled for an owner-draw child combo box, list box, or menu item when the control is created. CWnd informs Windows of the dimensions of the control.
CWnd::OnMenuCharCalled when the user presses a menu mnemonic character that doesn't match any of the predefined mnemonics in the current menu.
CWnd::OnMenuDragCalled when the user begins to drag a menu item.
CWnd::OnMenuGetObjectCalled when the mouse cursor enters a menu item or moves from the center of the item to the top or bottom of the item.
CWnd::OnMenuRButtonUpCalled when the user releases the right mouse button while the cursor is on a menu item.
CWnd::OnMenuSelectCalled when the user selects a menu item.
CWnd::OnMouseActivateCalled when the cursor is in an inactive window and the user presses a mouse button.
CWnd::OnMouseHoverCalled when the cursor hovers over the client area of the window for the period of time specified in a prior call to TrackMouseEvent.
CWnd::OnMouseHWheelCalled when the current window is composed by the Desktop Window Manager (DWM), and that window is maximized.
CWnd::OnMouseLeaveCalled when the cursor leaves the client area of the window specified in a prior call to TrackMouseEvent.
CWnd::OnMouseMoveCalled when the mouse cursor moves.
CWnd::OnMouseWheelCalled when a user rotates the mouse wheel. Uses Windows NT 4.0 message handling.
CWnd::OnMoveCalled after the position of the CWnd has been changed.
CWnd::OnMovingIndicates that a user is moving a CWnd object.
CWnd::OnNcActivateCalled when the non-client area needs to be changed to indicate an active or inactive state.
CWnd::OnNcCalcSizeCalled when the size and position of the client area need to be calculated.
CWnd::OnNcCreateCalled prior to OnCreate when the non-client area is being created.
CWnd::OnNcDestroyCalled when the non-client area is being destroyed.
CWnd::OnNcHitTestCalled by Windows every time the mouse is moved if CWnd contains the cursor or has captured mouse input with SetCapture.
CWnd::OnNcLButtonDblClkCalled when the user double-clicks the left mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcLButtonDownCalled when the user presses the left mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcLButtonUpCalled when the user releases the left mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcMButtonDblClkCalled when the user double-clicks the middle mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcMButtonDownCalled when the user presses the middle mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcMButtonUpCalled when the user releases the middle mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcMouseHoverCalled when the cursor hovers over the non-client area of the window for the period of time specified in a prior call to TrackMouseEvent.
CWnd::OnNcMouseLeaveThe framework calls this member function when the cursor leaves the non-client area of the window specified in a prior call to TrackMouseEvent.
CWnd::OnNcMouseMoveCalled when the cursor is moved within a non-client area of CWnd.
CWnd::OnNcPaintCalled when the non-client area needs painting.
CWnd::OnNcRButtonDblClkCalled when the user double-clicks the right mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcRButtonDownCalled when the user presses the right mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcRButtonUpCalled when the user releases the right mouse button while the cursor is within a non-client area of CWnd.
CWnd::OnNcRenderingChangedCalled when the rendering policy for the non-client area has changed.
CWnd::OnNcXButtonDblClkCalled when the user double-clicks XBUTTON1 or XBUTTON2 while the cursor is in the non-client area of a window.
CWnd::OnNcXButtonDownCalled when the user presses XBUTTON1 or XBUTTON2 of the mouse while the cursor is in the non-client area of a window.
CWnd::OnNcXButtonUpCalled when the user releases XBUTTON1 or XBUTTON2 of the mouse while the cursor is in the non-client area of a window.
CWnd::OnNextMenuCalled when the right or left arrow key is used to switch between the menu bar and the system menu.
CWnd::OnNotifyCalled by the framework to inform a parent window an event has occurred in one of its controls or that the control needs information.
CWnd::OnNotifyFormatCalled to determine if the current window accepts ANSI or Unicode structures in the WM_NOTIFY notification message.
CWnd::OnPaintCalled to repaint a portion of the window.
CWnd::OnPaintClipboardCalled when the client area of the Clipboard viewer needs repainting.
CWnd::OnPaletteChangedCalled to allow windows that use a color palette to realize their logical palettes and update their client areas.
CWnd::OnPaletteIsChangingInforms other applications when an application is going to realize its logical palette.
CWnd::OnParentNotifyCalled when a child window is created or destroyed, or when the user clicks a mouse button while the cursor is over the child window.
CWnd::OnPowerBroadcastCalled when a power-management event occurs.
CWnd::OnQueryDragIconCalled when a minimized (iconic) CWnd is about to be dragged by the user.
CWnd::OnQueryEndSessionCalled when the user chooses to end the Windows session.
CWnd::OnQueryNewPaletteInforms CWnd that it is about to receive the input focus.
CWnd::OnQueryOpenCalled when CWnd is an icon and the user requests that the icon be opened.
CWnd::OnQueryUIStateCalled to retrieve the user interface (UI) state for a window.
CWnd::OnRawInputCalled when the current window gets raw input.
CWnd::OnRButtonDblClkCalled when the user double-clicks the right mouse button.
CWnd::OnRButtonDownCalled when the user presses the right mouse button.
CWnd::OnRButtonUpCalled when the user releases the right mouse button.
CWnd::OnRenderAllFormatsCalled when the owner application is being destroyed and needs to render all its formats.
CWnd::OnRenderFormatCalled for the Clipboard owner when a particular format with delayed rendering needs to be rendered.
CWnd::OnSessionChangeCalled to notify an application of a change in session state.
CWnd::OnSetCursorCalled if mouse input is not captured and the mouse causes cursor movement within a window.
CWnd::OnSetFocusCalled after CWnd gains the input focus.
CWnd::OnSettingChangeCalled when the Win32 SystemParametersInfo function changes a system-wide setting.
CWnd::OnShowWindowCalled when CWnd is to be hidden or shown.
CWnd::OnSizeCalled after the size of CWnd has changed.
CWnd::OnSizeClipboardCalled when the size of the client area of the Clipboard-viewer window has changed.
CWnd::OnSizingIndicates that the user is resizing the rectangle.
CWnd::OnSpoolerStatusCalled from Print Manager whenever a job is added to or removed from the Print Manager queue.
CWnd::OnStyleChangedIndicates that the SetWindowLong Windows function has changed one or more of the window's styles.
CWnd::OnStyleChangingIndicates that the SetWindowLong Windows function is about to change one or more of the window's styles.
CWnd::OnSysCharCalled when a keystroke translates to a system character.
CWnd::OnSysColorChangeCalled for all top-level windows when a change is made in the system color setting.
CWnd::OnSysCommandCalled when the user selects a command from the Control menu, or when the user selects the Maximize or Minimize button.
CWnd::OnSysDeadCharCalled when a keystroke translates to a system dead character (such as accent characters).
CWnd::OnSysKeyDownCalled when the user holds down the ALT key and then presses another key.
CWnd::OnSysKeyUpCalled when the user releases a key that was pressed while the ALT key was held down.
CWnd::OnTCardCalled when the user clicks an authorable button.
CWnd::OnTimeChangeCalled for all top-level windows after the system time changes.
CWnd::OnTimerCalled after each interval specified in SetTimer.
CWnd::OnTouchInputProcess single input from Windows touch.
CWnd::OnTouchInputsProcess inputs from Windows touch.
CWnd::OnUniCharCalled when a key is pressed. That is, the current window has the keyboard focus and a WM_KEYDOWN message is translated by the TranslateMessage function.
CWnd::OnUnInitMenuPopupCalled when a drop-down menu or submenu has been destroyed.
CWnd::OnUpdateUIStateCalled to change the user interface (UI) state for the specified window and all its child windows.
CWnd::OnUserChangedCalled after the user has logged on or off.
CWnd::OnVKeyToItemCalled by a list box owned by CWnd in response to a WM_KEYDOWN message.
CWnd::OnVScrollCalled when the user clicks the window's vertical scroll bar.
CWnd::OnVScrollClipboardCalled when the owner should scroll the Clipboard image, invalidate the appropriate section, and update the scroll-bar values.
CWnd::OnWindowPosChangedCalled when the size, position, or Z-order has changed as a result of a call to SetWindowPos or another window-management function.
CWnd::OnWindowPosChangingCalled when the size, position, or Z-order is about to change as a result of a call to SetWindowPos or another window-management function.
CWnd::OnWinIniChangeCalled for all top-level windows after the Windows initialization file, WIN.INI, is changed.
CWnd::OnWndMsgIndicates if a windows message was handled.
CWnd::OnXButtonDblClkCalled when the user double-clicks XBUTTON1 or XBUTTON2 while the cursor is in the client area of a window.
CWnd::OnXButtonDownCalled when the user presses XBUTTON1 or XBUTTON2 while the cursor is in the client area of a window.
CWnd::OnXButtonUpCalled when the user releases XBUTTON1 or XBUTTON2 while the cursor is in the client area of a window.
CWnd::PostNcDestroyThis virtual function is called by the default OnNcDestroy function after the window has been destroyed.
CWnd::ReflectChildNotifyHelper function which reflects a message to its source.
CWnd::ReflectLastMsgReflects the last message to the child window.
CWnd::ResizeDynamicLayoutCalled by the framework when the window size changes to adjust the layout of child windows, if dynamic layout is enabled for the window.
CWnd::WindowProcProvides a window procedure for a CWnd. The default dispatches messages through the message map.

Public Operators

NameDescription
CWnd::operator HWNDCall to get a handle to a window.
CWnd::operator !=Determines if a window is not the same as the window whose handle is m_hWnd.
CWnd::operator ==Determines if a window is the same as the window whose handle is m_hWnd.

Public Data Members

NameDescription
CWnd::m_hWndIndicates the HWND attached to this CWnd.

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.

For more information on using CWnd, see Frame Windows and Window Objects.

CObject

CCmdTarget

CWnd

Header: afxwin.h

Called by the framework to perform the object's default action.

virtual HRESULT accDoDefaultAction(VARIANT varChild);

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

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

Override this function in your CWnd-derived class to perform your object's default action. For more information, see IAccessible::accDoDefaultAction in the Windows SDK.

Called by the framework to retrieve the child element or child object at a given point on the screen.

virtual HRESULT accHitTest(
    long xLeft,  
    long yTop,  
    VARIANT* pvarChild);

Parameters

xLeft
X-coordinate of the point to be hit tested (in screen units).

yTop
Y-coordinate of the point to be hit tested (in screen units).

pvarChild
Receives information identifying the object at the point specified by xLeft and yTop. See pvarID in IAccessible::accHitTest in the Windows SDK.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::accHitTest in the Windows SDK.

Called by the framework to retrieve the specified object's current screen location.

virtual HRESULT accLocation(
    long* pxLeft,  
    long* pyTop,  
    long* pcxWidth,  
    long* pcyHeight,  
    VARIANT varChild);

Parameters

pxLeft
Receives x-coordinate of the object's upper-left corner (in screen units).

pyTop
Receives y-coordinate of the object's upper-left corner (in screen units).

pcxWidth
Receives width of the object (in screen units).

pcyHeight
Receives height of the object (in screen units).

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.

Called by the framework to traverse to another user interface element within a container and if possible, retrieve the object.

virtual HRESULT accNavigate(
    long navDir,  
    VARIANT varStart,  
    VARIANT* pvarEndUpAt);

Parameters

navDir
Specifies the direction to navigate. See navDir in IAccessible::accNavigate in the Windows SDK.

varStart
Specifies the starting object. See varStart in IAccessible::accNavigate in the Windows SDK.

pvarEndUpAt
Receives information about the destination user interface object. See pvarEnd in IAccessible::accNavigate in the Windows SDK.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::accNavigate in the Windows SDK.

Called by the framework to modify the selection or move the keyboard focus of the specified object.

virtual HRESULT accSelect(
    long flagsSelect,  
    VARIANT varChild);

Parameters

flagsSelect
Specifies how to change the current selection or focus. See flagsSelect in IAccessible::accSelect in the Windows SDK.

varChild
Specifies the object to be selected. This parameter can be either CHILDID_SELF (to select the object itself) or a child ID (to select one of the object's children).

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::accSelect in the Windows SDK.

Produces special effects when showing or hiding windows.

BOOL AnimateWindow(
    DWORD dwTime,  
    DWORD dwFlags);

Parameters

dwTime
Specifies how long it takes to play the animation, in milliseconds. Typically, an animation takes 200 milliseconds to play.

dwFlags
Specifies the type of animation. For a full list of possible values, see AnimateWindow.

Return Value

Nonzero if the function succeeds; otherwise 0.

Remarks

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

Arranges all the minimized (iconic) child windows.

UINT ArrangeIconicWindows();

Return Value

The height of one row of icons if the function is successful; otherwise 0.

Remarks

This member function also arranges icons on the desktop window, which covers the entire screen. The GetDesktopWindow member function retrieves a pointer to the desktop window object.

To arrange iconic MDI child windows in an MDI client window, call CMDIFrameWnd::MDIIconArrange.

Example

// arrange minimized MDI child windows
// called from menu item; CMdiChildFrame is derived from CMDIChildWnd
void CMdiChildFrame::OnActionArrangeIconicWindows()
{
   UINT height = GetParent()->ArrangeIconicWindows();   
   TRACE(_T("height = %d\n"), height);
}

Attaches a Windows window to a CWnd object.

BOOL Attach(HWND hWndNew);

Parameters

hWndNew
Specifies a handle to a Windows window.

Return Value

Nonzero if successful; otherwise 0.

Example

This example shows how to use Attach and Detach to map to the MDI client window.

// Declare a CWnd member of CMainFrame
public:
   CWnd m_wndMDIClient;

   // detach MDI client window in CMainFrame destructor
   m_wndMDIClient.Detach();

   // In CMainFrame::OnCreate, attach MDI client window

	if (CMDIFrameWnd::OnCreate(lpCreateStruct) == -1)
		return -1;

   // attach MDI client window
   if (m_wndMDIClient.Attach(m_hWndMDIClient) == 0)
   {
      TRACE(_T("Failed to attach MDIClient.\n"));
      return -1;      // fail to create
   }

Call this member function to make a frame window modal.

virtual void BeginModalState();

Prepares CWnd for painting and fills a PAINTSTRUCT data structure with information about the painting.

CDC* BeginPaint(LPPAINTSTRUCT lpPaint);

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

void BindDefaultProperty(
    DISPID dwDispID,  
    VARTYPE vtProp,  
    LPCTSTR szFieldName,  
    CWnd* pDSCWnd);

Parameters

dwDispID
Specifies the DISPID of a property on a data-bound control that is to be bound to a data-source control.

vtProp
Specifies the type of the property to be bound — for example, VT_BSTR, VT_VARIANT, and so on.

szFieldName
Specifies the name of the column, in the cursor provided by the data-source control, to which the property will be bound.

pDSCWnd
Points to the window that hosts the data-source control to which the property will be bound. Call GetDlgItem with the resource ID of the DCS's host window to retrieve this pointer.

Remarks

The CWnd object on which you call this function must be a data-bound control.

Example

BindDefaultProperty might be used in the following context:

BOOL CMyDlg::OnInitDialog()
{

   CWnd* pDSC = GetDlgItem(IDC_DATASOURCE);
   CWnd* pMyBound = GetDlgItem(IDC_MYBOUNDCTRL1);
   pMyBound->BindDefaultProperty(0x1, VT_BSTR, _T("ContactFirstName"), pDSC);

	return TRUE;
}

Binds a cursor-bound property on a data-bound control (such as a grid control) to a data-source control and registers that relationship with the MFC binding manager.

void BindProperty(
    DISPID dwDispId,  
    CWnd* pWndDSC);

Parameters

dwDispId
Specifies the DISPID of a property on a data-bound control that is to be bound to a data-source control.

pWndDSC
Points to the window that hosts the data-source control to which the property will be bound. Call GetDlgItem with the resource ID of the DCS's host window to retrieve this pointer.

Remarks

The CWnd object on which you call this function must be a data-bound control.

Example

BindProperty might be used in the following context:

BOOL CMyDlg::OnInitDialog()
{

   CWnd* pDSC = GetDlgItem(IDC_DATASOURCE);
   CWnd* pMyBound = GetDlgItem(IDC_MYBOUNDCTRL2);
   pMyBound->BindProperty(0x1, pDSC);

	return TRUE;
}

Brings CWnd to the top of a stack of overlapping windows.

void BringWindowToTop();

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.

This function just calls the Win32 BringWindowToTop function. Call the SetWindowPos function to change a window's position in the Z-order. The BringWindowToTop function does not change the window style to make it a top-level window. For more information, see What's the difference between HWND_TOP and HWND_TOPMOST

Example

// Moves MDI child windows to the top when a mouse passes
// over it. CMdiView is derived from CView.
void CMdiView::OnMouseMove(UINT nFlags, CPoint point) 
{
   UNREFERENCED_PARAMETER(nFlags);
   UNREFERENCED_PARAMETER(point);

   GetParentFrame()->BringWindowToTop();
}

Calculates the window rectangle that can contain the specified client rectangle.

virtual void CalcWindowRect(
    LPRECT lpClientRect,  
    UINT nAdjustType = adjustBorder);

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.

For more usage restrictions, see AdjustWindowRectEx.

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);
}

Call this member function to remove a tool tip from the screen if a tool tip is currently displayed.

static void PASCAL CancelToolTips(BOOL bKeys = FALSE);

Parameters

bKeys
TRUE to cancel tool tips when a key is pressed and set the status bar text to the default; otherwise FALSE.

Remarks

System_CAPS_ICON_note.jpg Note

Using this member function has no effect on tool tips managed by your code. It only affects the tool tip control managed by CWnd::EnableToolTips.

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);
}

Centers a window relative to its parent.

void CenterWindow(CWnd* pAlternateOwner = NULL);

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.

Example

BOOL CAboutDlg::OnInitDialog()
{
   CDialog::OnInitDialog();

   CenterWindow();

   return TRUE;
}

Removes CWnd from the chain of Clipboard viewers and makes the window specified by hWndNext the descendant of the CWnd ancestor in the chain.

BOOL ChangeClipboardChain(HWND hWndNext);

Parameters

hWndNext
Identifies the window that follows CWnd in the Clipboard-viewer chain.

Return Value

Nonzero if successful; otherwise 0.

Selects (places a check mark next to) or clears (removes a check mark from) a button, or it changes the state of a three-state button.

void CheckDlgButton(
    int nIDButton,  
    UINT nCheck);

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.

Example

// Sets 3 check buttons in various ways.  Note BST_INDETERMINATE
// requires BS_3STATE or BS_AUTO3STATE in the button's style.
void CMyDlg::OnMarkButtons() 
{
   CheckDlgButton(IDC_CHECK1, BST_UNCHECKED);   // 0
   CheckDlgButton(IDC_CHECK2, BST_CHECKED);   // 1
   CheckDlgButton(IDC_CHECK3, BST_INDETERMINATE);   // 2
}

Selects (adds a check mark to) a given radio button in a group and clears (removes a check mark from) all other radio buttons in the group.

void CheckRadioButton(
    int nIDFirstButton,  
    int nIDLastButton,  
    int nIDCheckButton);

Parameters

nIDFirstButton
Specifies the integer identifier of the first radio button in the group.

nIDLastButton
Specifies the integer identifier of the last radio button in the group.

nIDCheckButton
Specifies the integer identifier of the radio button to be checked.

Remarks

The CheckRadioButton function sends a BM_SETCHECK message to the specified radio button.

Example

// Of the 4 radio buttons, selects radio button 3.
void CMyDlg::OnMarkRadio() 
{
   CheckRadioButton(IDC_RADIO1, IDC_RADIO4, IDC_RADIO3);   
}

Determines which, if any, of the child windows belonging to CWnd contains the specified point.

CWnd* ChildWindowFromPoint(
    POINT point) const;

 
 
CWnd* ChildWindowFromPoint(
    POINT point,  
    UINT nFlags) const;

 

Parameters

point
Specifies the client coordinates of the point to be tested.

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

ValueMeaning
CWP_ALLDo not skip any child windows
CWP_SKIPINVISIBLESkip invisible child windows
CWP_SKIPDISABLEDSkip disabled child windows
CWP_SKIPTRANSPARENTSkip 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.

Example

void CMyDlg::OnFindCenterChild() 
{
   CRect rect;
   GetClientRect(&rect);
   CWnd* pWnd = ChildWindowFromPoint(
      CPoint(rect.Width()/2, rect.Height()/2), 
      // Top left is always 0, 0.
      CWP_SKIPINVISIBLE);
   TRACE(_T("Center window is 0x%08x\n"), pWnd->m_hWnd);
}

Converts the client coordinates of a given point or rectangle on the display to screen coordinates.

void ClientToScreen(LPPOINT lpPoint) const;

 
 
void ClientToScreen(LPRECT lpRect) const;

 

Parameters

lpPoint
Points to a POINT structure or CPoint object that contains the client coordinates to be converted.

lpRect
Points to a RECT structure 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

// resize dialog to client's size
void CMyDlg::OnSizeToClient()
{
   CRect myRect;
   GetClientRect(&myRect);

   ClientToScreen(myRect);
   MoveWindow(myRect.left, myRect.top,
      myRect.Width(), myRect.Height());
}

Minimizes the window.

void CloseWindow();

Remarks

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

This member function is called by RunModalLoop to determine when the modal state should be exited.

virtual BOOL ContinueModal();

Return Value

Nonzero if modal loop is to be continued; 0 when EndModalLoop is called.

Remarks

By default, it returns non-zero until EndModalLoop is called.

Creates the specified child window and attaches it to the CWnd object.

virtual BOOL Create(
    LPCTSTR lpszClassName,  
    LPCTSTR lpszWindowName,  
    DWORD dwStyle,  
    Const RECT& rect,  
    CWnd* pParentWnd,  
    UINT nID,  
    CCreateContext* pContext = NULL);

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. 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 structure that is used to customize the document-view architecture for the application.

Return Value

TRUE if the method was successful; otherwise FALSE.

Remarks

System_CAPS_ICON_warning.jpg 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 function to register window classes. User defined window classes are available in the module where they are registered.

The CWnd::OnCreate method is called before the Create method returns, and before the window becomes visible.

Example

// Dynamically create static control using CWnd::Create,
// instead of with CStatic::Create, which doesn't
// need the "STATIC" class name.
void CMyDlg::OnCreateStatic() 
{
   // m_pWndStatic is a CWnd* member of CMyDlg
   m_pWndStatic = new CWnd;
   m_pWndStatic->Create(_T("STATIC"), _T("Hi"), WS_CHILD | WS_VISIBLE,
       CRect(0, 0, 20, 20), this, 1234);
}

Creates an Active Accessibility proxy for the specified object.

virtual HRESULT CreateAccessibleProxy(
    WPARAM wParam,  
    LPARAM lParam,  
    LRESULT* pResult);

Parameters

wParam
Identifies the object accessed by the Active Accessibility proxy. Can be one of the following values

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

Creates a new shape for the system caret and claims ownership of the caret.

void CreateCaret(CBitmap* pBitmap);

Parameters

pBitmap
Identifies the bitmap that defines the caret shape.

Remarks

The bitmap must have previously been created by the CBitmap::CreateBitmap member function, the CreateDIBitmap Windows function, or the 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 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

// Changes the caret of the edit control in this dialog box
void CMyDlg::OnChangeCaret() 
{
   m_pBitmapCaret = new CBitmap;
   m_pBitmapCaret->LoadBitmap(IDB_HAPPY_BITMAP);
   m_MyEdit.CreateCaret(m_pBitmapCaret);
   m_MyEdit.ShowCaret();
}

Use this member function to create an ActiveX control that will be represented in the MFC program by a CWnd object.

BOOL CreateControl(
    LPCTSTR pszClass,  
    LPCTSTR pszWindowName,  
    DWORD dwStyle,  
    const RECT& rect,  
    CWnd* pParentWnd,  
    UINT nID,  
    CFile* pPersist = NULL,  
    BOOL bStorage = FALSE,  
    BSTR bstrLicKey = NULL);

 
BOOL CreateControl(
    REFCLSID clsid,  
    LPCTSTR pszWindowName,  
    DWORD dwStyle,  
    const RECT& rect,  
    CWnd* pParentWnd,  
    UINT nID,  
    CFile* pPersist = NULL,  
    BOOL bStorage = FALSE,  
    BSTR bstrLicKey = NULL);

 
BOOL CreateControl(
    REFCLSID clsid,  
    LPCTSTR pszWindowName,  
    DWORD dwStyle,  
    const POINT* ppt,  
    const SIZE* psize,  
    CWnd* pParentWnd,  
    UINT nID,  
    CFile* pPersist = NULL,  
    BOOL bStorage = FALSE,  
    BSTR bstrLicKey = NULL);

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 object or a RECT structure.

ppt
Points to a POINT structure or CPoint object that contains the upper left corner of the control.

pSize
Points to a SIZE 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 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.

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

class CGenocx : public CWnd
{
protected:
   DECLARE_DYNCREATE(CGenocx)
public:
   CLSID const& GetClsid()
   {
      static CLSID const clsid
         = { 0x20DD1B9E, 0x87C4, 0x11D1, { 0x8B, 0xE3, 0x0, 0x0, 0xF8, 0x75, 0x4D, 0xA1 } };
      return clsid;
   }

   // This code is generated by the Control Wizard.
   // It wraps the call to CreateControl in the call to Create.
   virtual BOOL Create(LPCTSTR lpszClassName, LPCTSTR lpszWindowName, DWORD dwStyle,
                  const RECT& rect, CWnd* pParentWnd, UINT nID, 
                  CCreateContext* pContext = NULL)
   { 
      UNREFERENCED_PARAMETER(pContext);
      UNREFERENCED_PARAMETER(lpszClassName);

      return CreateControl(GetClsid(), lpszWindowName, dwStyle, rect, pParentWnd, nID); 
   }

   // remainder of class declaration omitted...

Creates the specified window and attaches it to the CWnd object.

virtual BOOL CreateEx(
    DWORD dwExStyle,  
    LPCTSTR lpszClassName,  
    LPCTSTR lpszWindowName,  
    DWORD dwStyle,  
    int x,  
    int y,  
    int nWidth,  
    int nHeight,  
    HWND hWndParent,  
    HMENU nIDorHMenu,  
    LPVOID lpParam = NULL);

 
virtual BOOL CreateEx(
    DWORD dwExStyle,  
    LPCTSTR lpszClassName,  
    LPCTSTR lpszWindowName,  
    DWORD dwStyle,  
    const RECT& rect,  
    CWnd* pParentWnd,  
    UINT nID,  
    LPVOID lpParam = NULL);

Parameters

dwExStyle
Bitwise combination (OR) of extended window styles; 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; 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 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

System_CAPS_ICON_warning.jpg 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 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 method is called before the CreateEx method returns, and before the window becomes visible.

Example

void CMyDlg::OnCreateExtendedControl() 
{
   // m_pWndStaticEx is a CWnd* member of CMyDlg
   m_pWndStaticEx = new CStatic;
   m_pWndStaticEx->CreateEx(WS_EX_CLIENTEDGE, // Make a client edge label.
      _T("STATIC"), _T("Hi"),
      WS_CHILD | WS_TABSTOP | WS_VISIBLE,
      5, 5, 30, 30, m_hWnd, (HMENU)2345);
}

Creates a gray rectangle for the system caret and claims ownership of the caret.

void CreateGrayCaret(
    int nWidth,  
    int nHeight);

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

// Create a 5x10 gray caret in the edit control.
void CMyDlg::OnCreateGrayCaret()
{
   m_MyEdit.CreateGrayCaret(5, 10);
   m_MyEdit.ShowCaret();
}

Creates a solid rectangle for the system caret and claims ownership of the caret.

void CreateSolidCaret(
    int nWidth,  
    int nHeight);

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

// Create a 5x10 solid caret in the edit control.
void CMyDlg::OnCreateSolidCaret()
{
   m_MyEdit.CreateSolidCaret(5, 10);
   m_MyEdit.ShowCaret();
}

Constructs a CWnd object.

CWnd();

Remarks

The Windows window is not created and attached until the CreateEx or Create member function is called.

Calls the default window procedure.

LRESULT Default();

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

// This sample shows how to avoid any button handling in base class,
// if any, and call the default window procedure directly.
void CMyDlg::OnLButtonDown(UINT nFlags, CPoint point)
{
   UNREFERENCED_PARAMETER(nFlags);
   UNREFERENCED_PARAMETER(point);

   CWnd::Default();
}

Calls the default window procedure, which provides default processing for any window message that an application does not process.

virtual LRESULT DefWindowProc(
    UINT message,  
    WPARAM wParam,  
    LPARAM lParam);

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.

Called automatically by the idle time handler of the CWinApp object.

static void PASCAL DeleteTempMap();

Remarks

Deletes any temporary CWnd objects created by the FromHandle member function.

Example

   // DeleteTempMap() is a static member and does not need 
   // to be called within the scope of an instantiated CWnd object.
   CWnd::DeleteTempMap();

Destroys the Windows window attached to the CWnd object.

virtual BOOL DestroyWindow();

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

If the CWnd being destroyed is a child window and does not have the WS_EX_NOPARENTNOTIFY style set, then the WM_PARENTNOTIFY message is sent to the parent.

Example

// CModeless is a CDialog class representing a modeless dialog
// Destruction of the modeless dialog involves calling DestroyWindow in 
// OnOK() & OnCancel() handlers
void CModeless::OnOK() 
{ 
   if (!UpdateData(TRUE)) 
   {
      TRACE(_T("UpdateData failed during dialog termination\n"));
      // The UpdateData routine will set focus to correct item
      return;
   }
   DestroyWindow();
}

void CModeless::OnCancel()
{
   DestroyWindow();
}

Detaches a Windows handle from a CWnd object and returns the handle.

HWND Detach();

Return Value

A HWND to the Windows object.

Example

See the example for CWnd::Attach.

Fills a list box with a file or directory listing.

int DlgDirList(
    LPTSTR lpPathSpec,  
    int nIDListBox,  
    int nIDStaticPath,  
    UINT nFileType);

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 and LB_DIR 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

   // If pDialog points to a CDialog object with a list box
   // with the identifier IDC_DIRLIST, this call will populate
   // the box with only the non-hidden subdirectories in the root
   // directory of the C:\ drive.
   TCHAR path[MAX_PATH];
   _tcscpy_s(path, MAX_PATH, _T("C:\\"));

   pDialog->DlgDirList(path, IDC_DIRLIST, 0, DDL_EXCLUSIVE | DDL_DIRECTORY);

Fills the list box of a combo box with a file or directory listing.

int DlgDirListComboBox(
    LPTSTR lpPathSpec,  
    int nIDComboBox,  
    int nIDStaticPath,  
    UINT nFileType);

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 and CB_DIR 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

   // If pDialog points to a CDialog object with a combo box
   // with the identifier IDC_DIRCOMBO, this call will populate
   // the box with only the non-hidden subdirectories in the root
   // directory of the C:\ drive. 

   TCHAR szPath[MAX_PATH];
   _tcsncpy_s(szPath, MAX_PATH, _T("C:\\"), MAX_PATH);
   pDialog->DlgDirListComboBox(szPath, IDC_DIRCOMBO, 0, DDL_EXCLUSIVE | 
      DDL_DIRECTORY);

   // Note that the first argument is a string and not a string 
   // literal. This is necessary because DlgDirListComboBox 
   // modifies the supplied string. Passing a string literal 
   // will result in an access violation.   

Retrieves the current selection from a list box.

BOOL DlgDirSelect(
    LPTSTR lpString,  
    int nIDListBox);

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

Retrieves the current selection from the list box of a combo box.

BOOL DlgDirSelectComboBox(
    LPTSTR lpString,  
    int nIDComboBox);

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 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 and CB_GETLBTEXT messages to the combo box.

It does not allow more than one filename to be returned from a combo box.

Called by the framework to exchange and validate dialog data.

virtual void DoDataExchange(CDataExchange* pDX);

Parameters

pDX
A pointer to a CDataExchange object.

Remarks

Never call this function directly. It is called by the 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, 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:

void CPenWidthsDlg::DoDataExchange(CDataExchange* pDX)
{
   CDialog::DoDataExchange(pDX);
   DDX_Text(pDX, IDC_THINPENWIDTH, m_nThinWidth);
	DDV_MinMaxInt(pDX, m_nThinWidth, 1, 20);
   DDX_Text(pDX, IDC_THICKPENWIDTH, m_nThickWidth);
   DDV_MinMaxInt(pDX, m_nThickWidth, 1, 20);
}

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 and Dialog Data Exchange and Validation. For a description of the DDX_ and DDV_ macros generated by the Add Variable wizard, see Technical Note 26.

Call this member function from within a window, using a CWnd pointer, in your application's CWinApp::InitInstance function to indicate that the window accepts dropped files from the Windows File Manager or File Explorer.

void DragAcceptFiles(BOOL bAccept = TRUE);

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.

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.

BOOL DragDetect(POINT pt) const;

 

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, as described in the Windows SDK.

Draws a wire-frame rectangle and animates it to indicate the opening of an icon or the minimizing or maximizing of a window.

BOOL DrawAnimatedRects(
    int idAni,  
    CONST RECT* lprcFrom,  
    CONST RECT* lprcTo);

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 structure specifying the location and size of the icon or minimized window.

lprcTo
Pointer to a RECT 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, as described in the Windows SDK.

Draws a window caption.

BOOL DrawCaption(
    CDC* pDC,  
    LPCRECT lprc,  
    UINT uFlags);

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.

Return Value

Nonzero if the function succeeds; otherwise 0.

Remarks

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

Redraws the menu bar.

void DrawMenuBar();

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.

Enables user-defined Active Accessibility functions.

void EnableActiveAccessibility();

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 in your class, and you must call EnableActiveAccessibility in the class's constructor.

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.

void EnableDynamicLayout(BOOL bEnable = TRUE);

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.

Enables or disables window D2D support. Call this method before the main window is initialized.

void EnableD2DSupport(
    BOOL bEnable = TRUE,  
    BOOL bUseDCRenderTarget = FALSE);

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.

Enables or disables one or both arrows of a scroll bar.

BOOL EnableScrollBar(
    int nSBFlags,  
    UINT nArrowFlags = ESB_ENABLE_BOTH);

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.

Enables or disables the scroll bar for this window.

void EnableScrollBarCtrl(
    int nBar,  
    BOOL bEnable = TRUE);

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.

Enables tool tips for the given window.

BOOL EnableToolTips(BOOL bEnable = TRUE);

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 to provide the TOOLINFO struct or structs for the window.

System_CAPS_ICON_note.jpg Note

Some windows, such as CToolBar, provide a built-in implementation of OnToolHitTest.

See TOOLINFO in the Windows SDK 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.

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

   // From message map for CMdiView, a CView-derived class
   ON_NOTIFY_EX_RANGE(TTN_NEEDTEXTW, 0, 0xFFFF, &CMdiView::OnToolTipNotify)
   ON_NOTIFY_EX_RANGE(TTN_NEEDTEXTA, 0, 0xFFFF, &CMdiView::OnToolTipNotify)

void CMdiView::OnInitialUpdate()
{
   CView::OnInitialUpdate();

   m_Edit.Create(ES_MULTILINE | WS_CHILD | WS_VISIBLE | WS_TABSTOP | WS_BORDER,
      CRect(10, 10, 100, 100), this, IDC_TTEDIT);
   EnableToolTips(TRUE);   // enable tool tips for view
}

//Notification handler
BOOL CMdiView::OnToolTipNotify(UINT id, NMHDR* pNMHDR, LRESULT* pResult)
{
   UNREFERENCED_PARAMETER(id);
   UNREFERENCED_PARAMETER(pResult);

   // need to handle both ANSI and UNICODE versions of the message
   TOOLTIPTEXTA* pTTTA = (TOOLTIPTEXTA*)pNMHDR;
   TOOLTIPTEXTW* pTTTW = (TOOLTIPTEXTW*)pNMHDR;
   CStringA strTipText;
   UINT_PTR nID = pNMHDR->idFrom;
   if (pNMHDR->code == TTN_NEEDTEXTA && (pTTTA->uFlags & TTF_IDISHWND) ||
      pNMHDR->code == TTN_NEEDTEXTW && (pTTTW->uFlags & TTF_IDISHWND))
   {
      // idFrom is actually the HWND of the tool
      nID = ::GetDlgCtrlID((HWND)nID);
   }

   if (nID != 0) // will be zero on a separator
      strTipText.Format("Control ID = %d", nID);

   if (pNMHDR->code == TTN_NEEDTEXTA)
   {
      strncpy_s(pTTTA->szText, sizeof(pTTTA->szText), strTipText, 
         strTipText.GetLength() + 1);
   }
   else
   {
      ::MultiByteToWideChar(CP_ACP , 0, strTipText, strTipText.GetLength() + 1,
         pTTTW->szText, sizeof(pTTTW->szText)/(sizeof pTTTW->szText[0]));
   }

   return TRUE;    // message was handled
}

Enables or disables tracking tooltips.

BOOL EnableTrackingToolTips(BOOL bEnable = TRUE);

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.

Enables or disables mouse and keyboard input.

BOOL EnableWindow(BOOL bEnable = TRUE);

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

//CMyFileDialog is a CFileDialog-derived class
//OnInitDialog is the handler for WM_INITDIALOG
BOOL CMyFileDialog::OnInitDialog() 
{
   CFileDialog::OnInitDialog();

   CWnd* pWndParent = GetParent();

   //make sure you add #include <dlgs.h> for IDs 'edt1' & 'stc3'

   //disables the 'file name' edit and static control
   //of the standard file open dialog

   //get handle of 'file name' combobox control & disable it
   CWnd* pWnd = pWndParent->GetDlgItem(cmb13);
   pWnd->EnableWindow(FALSE);

   //get handle of 'file name' static control & disable it
   pWnd = pWndParent->GetDlgItem(stc3);
   pWnd->EnableWindow(FALSE);
   
   return TRUE;
}

Terminates a call to RunModalLoop.

virtual void EndModalLoop(int nResult);

Parameters

nResult
Contains the value to be returned to the caller of RunModalLoop.

Remarks

The nResult parameter is propagated to the return value from RunModalLoop.

Call this member function to change a frame window from modal to modeless.

virtual void EndModalState();

Marks the end of painting in the given window.

void EndPaint(LPPAINTSTRUCT lpPaint);

Parameters

lpPaint
Points to a PAINTSTRUCT structure that contains the painting information retrieved by the 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.

Initiates a dialog resource.

BOOL ExecuteDlgInit(LPCTSTR lpszResourceName);

 
BOOL ExecuteDlgInit(LPVOID lpResource);

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.

Called by the framework to display tool tip messages.

void FilterToolTipMessage(MSG* pMsg);

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.

Returns the top-level CWnd whose window class is given by lpszClassName and whose window name, or title, is given by lpszWindowName.

static CWnd* PASCAL FindWindow(
    LPCTSTR lpszClassName,  
    LPCTSTR lpszWindowName);

Parameters

lpszClassName
Points to a null-terminated string that specifies the window's class name (a WNDCLASS structure). If lpClassName is NULL, all class names match.

lpszWindowName
Points to a null-terminated string that specifies the window name (the window's title). If lpWindowName is NULL, all window names match.

Return Value

Identifies the window that has the specified class name and window name. It is NULL if no such window is found.

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

Remarks

This function does not search child windows.

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 window
      if (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 application
      return FALSE;
   }

   return TRUE;
}

Retrieves the window object whose class name and window name match the specified strings.

static CWnd* FindWindowEx(
    HWND hwndParent,  
    HWND hwndChildAfter,  
    LPCTSTR lpszClass,  
    LPCTSTR lpszWindow);

Parameters

hwndParent
Handle to the parent window whose child windows are to be searched.

hwndChildAfter
Handle to a child window. The search begins with the next child window in the Z order. The child window must be a direct child window of hwndParent, not just a descendant window.

lpszClass
Pointer to a null-terminated string that specifies the class name or a class atom created by a previous call to the RegisterClass or RegisterClassEx.

lpszWindow
Pointer to a null-terminated string that specifies the window name (the window's title). If this parameter is NULL, all window names match.

Return Value

If the function succeeds, the return value is a pointer to the window object having the specified class and window names. If the function fails, the return value is NULL.

Remarks

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

Flashes the given window once.

BOOL FlashWindow(BOOL bInvert);

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.

Example

BOOL CPenWidthsDlg::OnInitDialog()
{
   CDialog::OnInitDialog();

   // set timer to cause dialog to flash
   SetTimer(1, 500, NULL);
   return TRUE;  // return TRUE unless you set the focus to a control
}

void CPenWidthsDlg::OnTimer(UINT_PTR nIDEvent)
{
   // cause the dialog to flash
   FlashWindow(TRUE);
   CDialog::OnTimer(nIDEvent);
}

Flashes the given window.

BOOL FlashWindowEx(
    DWORD dwFlags,  
    UINT uCount,  
    DWORD dwTimeout);

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.

Returns a pointer to a CWnd object when given a handle to a window. If a CWnd object is not attached to the handle, a temporary CWnd object is created and attached.

static CWnd* PASCAL FromHandle(HWND hWnd);

Parameters

hWnd
An HWND of a Windows window.

Return Value

Returns a pointer to a CWnd object when given a handle to a window. 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.

Returns a pointer to a CWnd object when given a handle to a window.

static CWnd* PASCAL FromHandlePermanent(HWND hWnd);

Parameters

hWnd
An HWND of a Windows window.

Return Value

A pointer to a CWnd object.

Remarks

If a CWnd object is not attached to the handle, NULL is returned.

This function, unlike FromHandle, does not create temporary objects.

Called by the framework to retrieve the address of an IDispatch interface for the specified child.

virtual HRESULT get_accChild(
    VARIANT varChild,  
    IDispatch** ppdispChild);

Parameters

varChild
Identifies the child whose IDispatch interface is to be retrieved.

ppdispChild
Receives the address of the child object's IDispatch interface.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::get_accChild in the Windows SDK.

Called by the framework to retrieve the number of children belonging to this object.

virtual HRESULT get_accChildCount(long* pcountChildren);

Parameters

pcountChildren
Receives the number of children.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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.

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

Called by the framework to retrieve a string that describes the object's default action.

virtual HRESULT get_accDefaultAction(
    VARIANT varChild,  
    BSTR* pszDefaultAction);

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.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

Override this function in your CWnd-derived class to describe your object's default action.

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

Called by framework to retrieve a string that describes the visual appearance of the specified object.

virtual HRESULT get_accDescription(
    VARIANT varChild,  
    BSTR* pszDescription);

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.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

Override this function in your CWnd-derived class to describe your object. Call the base class version and add your description.

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

Called by the framework to retrieve the object that has the keyboard focus.

virtual HRESULT get_accFocus(VARIANT* pvarChild);

Parameters

pvarChild
Receives information about the object that has the focus. See pvarID in IAccessible::get_accFocus in the Windows SDK.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::get_accFocus in the Windows SDK.

Called by the framework to retrieve an object's Help property string.

virtual HRESULT get_accHelp(
    VARIANT varChild,  
    BSTR* pszHelp);

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.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

Override this function in your CWnd-derived class to provide help text for your object.

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

Called by the framework to retrieve the full path of the WinHelp file associated with the specified object and the identifier of the appropriate topic within that file.

virtual HRESULT get_accHelpTopic(
    BSTR* pszHelpFile,  
    VARIANT varChild,  
    long* pidTopic);

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

pidTopic
Identifies the Help file topic associated with the specified object. See pidTopic in IAccessible::get_accHelpTopic in the Windows SDK.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

Override this function in your CWnd-derived class to provide help information about your object.

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

Called by the framework to retrieve the specified object's shortcut key or access key.

virtual HRESULT get_accKeyboardShortcut(
    VARIANT varChild,  
    BSTR* pszKeyboardShortcut);

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.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

Override this function in your CWnd-derived class to identify the keyboard shortcut for your object.

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

Called by the framework to retrieve the name of the specified object.

virtual HRESULT get_accName(
    VARIANT varChild,  
    BSTR* pszName);

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.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

Override this function in your CWnd-derived class to return the name of your object.

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

Called by the framework to retrieve the IDispatch interface of the object's parent.

virtual HRESULT get_accParent(IDispatch** ppdispParent);

Parameters

ppdispParent
Receives the address of the parent object's IDispatch interface. The variable is set to NULL if no parent exists, or if the child cannot access its parent.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

In most cases you don't have to override this function.

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

Called by the framework to retrieve information that describes the role of the specified object.

virtual HRESULT get_accRole(
    VARIANT varChild,  
    VARIANT* pvarRole);

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

pvarRole
Receives the role information. See pvarRole in IAccessible::get_accRole in the Windows SDK.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::get_accRole in the Windows SDK.

Called by the framework to retrieve the selected children of this object.

virtual HRESULT get_accSelection(VARIANT* pvarChildren);

Parameters

pvarChildren
Receives information about which children are selected. See pvarChildren in IAccessible::get_accSelection in the Windows SDK.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::get_accSelection in the Windows SDK.

Called by the framework to retrieve the current state of the specified object.

virtual HRESULT get_accState(
    VARIANT varChild,  
    VARIANT* pvarState);

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

pvarState
Receives information about the object's state. See pvarState in IAccessible::get_accState in the Windows SDK.

Return Value

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

Remarks

This function is part of MFC's Active Accessibility support.

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::get_accState in the Windows SDK.

Called by the framework to retrieve the value of the specified object.

virtual HRESULT get_accValue(
    VARIANT varChild,  
    BSTR* pszValue);

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

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

Remarks

This function is part of MFC's Active Accessibility support.

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::get_accValue in the Windows SDK.

Retrieves a pointer to the active window.

static CWnd* PASCAL GetActiveWindow();

Return Value

The active window or NULL if no window was active at the time of the call. The pointer may be temporary and should not be stored for later use.

Remarks

The active window is either the window that has the current input focus or the window explicitly made active by the SetActiveWindow member function.

Retrieves the ancestor window object of the specified window.

CWnd* GetAncestor(UINT gaFlags) const;

 

Parameters

gaFlags
Specifies the ancestor to be retrieved. For a complete list of possible values, see GetAncestor.

Return Value

If the function succeeds, the return value is a pointer to the ancestor window object. If the function fails, the return value is NULL.

Remarks

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

Retrieves the window that has the mouse capture.

static CWnd* PASCAL GetCapture();

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.

Retrieves the client coordinates of the caret's current position and returns them as a CPoint.

static CPoint PASCAL GetCaretPos();

Return Value

CPoint object containing the coordinates of the caret's position.

Remarks

The caret position is given in the client coordinates of the CWnd window.

Retrieves the ID of the currently checked radio button in the specified group.

int GetCheckedRadioButton(
    int nIDFirstButton,  
    int nIDLastButton);

Parameters

nIDFirstButton
Specifies the integer identifier of the first radio button in the group.

nIDLastButton
Specifies the integer identifier of the last radio button in the group.

Return Value

ID of the checked radio button, or 0 if none is selected.

Copies the client coordinates of the CWnd client area into the structure pointed to by lpRect.

void GetClientRect(LPRECT lpRect) const;

 

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

See the example for CWnd::IsIconic.

Retrieves the current owner of the Clipboard.

static CWnd* PASCAL GetClipboardOwner();

Return Value

Identifies the window that owns the Clipboard if the function is successful. Otherwise, it is NULL.

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

Remarks

The Clipboard can still contain data even if it is not currently owned.

Retrieves the first window in the Clipboard-viewer chain.

static CWnd* PASCAL GetClipboardViewer();

Return Value

Identifies the window currently responsible for displaying the Clipboard if successful; otherwise NULL (for example, if there is no viewer).

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

Call this member function to retrieve a pointer to an unknown OLE control.

LPUNKNOWN GetControlUnknown();

Return Value

A pointer to the IUnknown interface of the OLE control represented by this CWnd object. If this object does not represent an OLE control, the return value is NULL.

Remarks

You should not release this IUnknown pointer. Typically, you would use to obtain a specific interface of the control.

The interface pointer returned by GetControlUnknown is not reference-counted. Do not call IUnknown::Release on the pointer unless you have previously called IUnknown::AddRef on it.

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

Returns a pointer to the message this window is currently processing. Should only be called when in an OnMessage message-handler member function.

static const MSG* PASCAL GetCurrentMessage();

Return Value

Returns a pointer to the MSG structure that contains the message the window is currently processing. Should only be called when in an OnMessage handler.

Example

See the example for CMDIFrameWnd::MDICascade.

Retrieves a pointer to a common, class, or private device context for the client area depending on the class style specified for the CWnd.

CDC* GetDC();

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.

Retrieves the handle of a device context for the CWnd window.

CDC* GetDCEx(
    CRgn* prgnClip,  
    DWORD flags);

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.

Retrieves the device context (DC) render target for the CWnd window.

CDCRenderTarget* GetDCRenderTarget();

Return Value

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

Remarks

Call this member function to find the descendant window specified by the given ID.

CWnd* GetDescendantWindow(
    int nID,  
    BOOL bOnlyPerm = FALSE) const;

 

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.

Returns the Windows desktop window.

static CWnd* PASCAL GetDesktopWindow();

Return Value

Identifies the Windows desktop window. This pointer may be temporary and should not be stored for later use.

Remarks

The desktop window covers the entire screen and is the area on top of which all icons and other windows are painted.

Returns the window or control ID value for any child window, not only that of a control in a dialog box.

int GetDlgCtrlID() const;

 

Return Value

The numeric identifier of the CWnd child window if the function is successful; otherwise 0.

Remarks

Since top-level windows do not have an ID value, the return value of this function is invalid if the CWnd is a top-level window.

Example

See the example for CWnd::OnCtlColor.

Retrieves a pointer to the specified control or child window in a dialog box or other window.

CWnd* GetDlgItem(
    int nID) const;

 
 
void GetDlgItem(
    int nID,  
    HWND* phWnd) const;

 

Parameters

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

phWnd
A pointer to a child window.

Return Value

A pointer to the given control or child window. If no control with the integer ID given by the nID parameter exists, the value is NULL.

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

Remarks

The pointer returned is usually cast to the type of control identified by nID.

Example

   // uses GetDlgItem to return a pointer to a user interface control
   CEdit* pBoxOne;
   pBoxOne = (CEdit*)GetDlgItem(IDC_MYEDIT);
   GotoDlgCtrl(pBoxOne);

Retrieves the text of the control identified by nID.

UINT GetDlgItemInt(
    int nID,  
    BOOL* lpTrans = NULL,  
    BOOL bSigned = TRUE) const;

 

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.

It sends a WM_GETTEXT message to the control.

Call this member function to retrieve the title or text associated with a control in a dialog box.

int GetDlgItemText(
    int nID,  
    LPTSTR lpStr,  
    int nMaxCount) const;

 
 
int GetDlgItemText(
    int nID,  
    CString& rString) const;

 

Parameters

nID
Specifies the integer identifier of the control whose title is to be retrieved.

lpStr
Points to the buffer to receive the control's title or text.

nMaxCount
Specifies the maximum length (in characters) of the string to be copied to lpStr. If the string is longer than nMaxCount, it is truncated.

rString
A reference to a CString.

Return Value

Specifies the actual number of characters copied to the buffer, not including the terminating null character. The value is 0 if no text is copied.

Remarks

The GetDlgItemText member function copies the text to the location pointed to by lpStr and returns a count of the number of bytes it copies.

Call this member function to retrieve a pointer to the underlying cursor that is defined by the DataSource, UserName, Password, and SQL properties of the data-source control.

IUnknown* GetDSCCursor();

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:

Example

BOOL CMyDlg::OnInitDialog()
{

   // Find the child controls on the dialog
   HRESULT hr = E_FAIL;
   CWnd* pDSC = GetDlgItem(IDC_DATASOURCE);
   CWnd* pListWnd = GetDlgItem(IDC_DBLIST1);
   IUnknown* punkList = pListWnd->GetControlUnknown();
   IDBList* pList = NULL;

   if (NULL != punkList)
   {
      hr = punkList->QueryInterface(__uuidof(IDBList), (void**)&pList);
   }

   if (SUCCEEDED(hr))
   {
      // Tell the MFC binding manager that we are
      // binding DISPID 3 to the data-source control.
      pListWnd->BindProperty(0x3, pDSC);

      // Tell the listbox which field to expose as its bound column
      pList->put_BoundColumn(_T("ContactFirstName"));

      // Tell the listbox which cursor and column to populate its list from
      pList->put_ListField(_T("ContactFirstName"));

      IUnknown* punkCursor = pDSC->GetDSCCursor();
      if (NULL != punkCursor)
      {
         punkCursor->Release();
      }

      pList->Release();

	return TRUE;
}

Retrieves a pointer to the dynamic layout manager object.

CMFCDynamicLayout* GetDynamicLayout();

Return Value

A pointer to the dynamic layout manager object, or NULL if dynamic layout is not enabled.

Remarks

The window object owns and manages the lifetime of the returned pointer, so it should only be used to access the object; do not delete the pointer or store the pointer permanently.

Returns the window's extended style.

DWORD GetExStyle() const;

 

Return Value

The window's extended style. For more information about the extended window styles used in MFC, see Extended Window Styles.

Retrieves a pointer to the CWnd that currently has the input focus.

static CWnd* PASCAL GetFocus();

Return Value

A pointer to the window that has the current focus, or NULL if there is no focus window.

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

Sends the WM_GETFONT message to the window to retrieve the current font.

CFont* GetFont() const;

 

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.

Returns a pointer to the foreground window (the window with which the user is currently working).

static CWnd* PASCAL GetForegroundWindow();

Return Value

A pointer to the foreground window. This may be a temporary CWnd object.

Remarks

The foreground window applies only to top-level windows (frame windows or dialog boxes).

Call this member function to get the handle to either a big (32x32) or the handle to a small (16x16) icon, as indicated by bBigIcon.

HICON GetIcon(BOOL bBigIcon) const;

 

Parameters

bBigIcon
Specifies a 32 pixel by 32 pixel icon if TRUE; specifies a 16 pixel by 16 pixel icon if FALSE.

Return Value

A handle to an icon. If unsuccessful, returns NULL.

Determines which pop-up window owned by CWnd was most recently active.

CWnd* GetLastActivePopup() const;

 

Return Value

Identifies the most recently active pop-up window. The return value will be the window itself if any of the following conditions are met:

  • The window itself was most recently active.

  • The window does not own any pop-up windows.

  • The window is not a top-level window or is owned by another window.

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

Example

See the example for CWnd::FindWindow.

Retrieves the opacity and transparency color key of a layered window.

BOOL GetLayeredWindowAttributes(
    COLORREF* pcrKey,  
    BYTE* pbAlpha,  
    DWORD* pdwFlags) const;

 

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.

Return Value

Nonzero if the function succeeds; otherwise 0.

Remarks

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

Retrieves a pointer to the menu for this window.

CMenu* GetMenu() const;

 

Return Value

Identifies the menu. The value is NULL if CWnd has no menu. The return value is undefined if CWnd is a child window.

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

Remarks

This function should not be used for child windows because they do not have a menu.

Example

void CMainFrame::OnCwndDeletefilemenu()
{
   // This example deletes the leftmost popup menu or leftmost
   // popup menu item from the application's main window.
   CWnd* pMain = AfxGetMainWnd();

   // The main window _can_ be NULL, so this code
   // doesn't ASSERT and actually tests.
   if (pMain != NULL)
   {
      // Get the main window's menu
      CMenu* pMenu = pMain->GetMenu();

      // If there is a menu and it has items, we'll
      // delete the first one.
      if (pMenu != NULL && pMenu->GetMenuItemCount() > 0)
      {
         pMenu->DeleteMenu(0, MF_BYPOSITION);
         // force a redraw of the menu bar
         pMain->DrawMenuBar();
      }

      // No need to delete pMenu because it is an MFC
      // temporary object.
   }
}

Retrieves information about the specified menu bar.

BOOL GetMenuBarInfo(
    LONG idObject,  
    LONG idItem,  
    PMENUBARINFO pmbi) const;

 

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.

Searches for the previous or next control within a group of controls in a dialog box.

CWnd* GetNextDlgGroupItem(
    CWnd* pWndCtl,  
    BOOL bPrevious = FALSE) const;

 
 
COleControlSiteOrWnd* GetNextDlgGroupItem(
    COleControlSiteOrWnd* pCurSiteOrWnd = NULL) const;

 

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.

System_CAPS_ICON_note.jpg 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 typeIdentifying information
Windowed ActiveX controlContains 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 controlContains no HWND. The m_pSite member of COleControlSiteOrWnd points to the control's COleControlSite, and the m_hWnd member is NULL.
Standard windowContains just an HWND. The m_hWnd member of COleControlSiteOrWnd is set to the HWND of the window, and the m_pSite member is NULL.

Retrieves a pointer to the first control that was created with the WS_TABSTOP style and that precedes or follows the specified control.

CWnd* GetNextDlgTabItem(
    CWnd* pWndCtl,  
    BOOL bPrevious = FALSE) const;

 
 
COleControlSiteOrWnd* GetNextDlgTabItem(
    COleControlSiteOrWnd* pCurSiteOrWnd,  
    BOOL bPrevious) const;

 

Parameters

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

pCurSiteOrWnd
Identifies the COleControlSiteOrWnd control. For more information about COleControlSiteOrWnd, see CWnd::GetNextDlgGroupItem.

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

Return Value

Pointer to the previous or next control that has the WS_TABSTOP style, if the member function is successful.

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

For more information about COleControlSiteOrWnd, see CWnd::GetNextDlgGroupItem.

Searches for the next (or previous) window in the window manager's list.

CWnd* GetNextWindow(UINT nFlag = GW_HWNDNEXT) const;

 

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.

Retrieves the custom site for the specified ActiveX control.

COleControlSite* GetOleControlSite(UINT idControl) const;

 

Parameters

idControl
The ID of the ActiveX control.

Retrieves the handle of the window that currently has the Clipboard open.

static CWnd* PASCAL GetOpenClipboardWindow();

Return Value

The handle of the window that currently has the Clipboard open if the function is successful; otherwise NULL.

Retrieves a pointer to the owner of the window.

CWnd* GetOwner() const;

 

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.

Call this function to get a pointer to a child window's parent window (if any).

CWnd* GetParent() const;

 

Return Value

See the Return Values section in GetParent in the Windows SDK.

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.

Call this member function to retrieve the parent frame window.

CFrameWnd* GetParentFrame() const;

 

Return Value

A pointer to a frame window if successful; otherwise NULL.

Remarks

The member function searches up the parent chain until a CFrameWnd (or derived class) object is found.

Call this member function to get a pointer to a child window's parent window or owner window.

CWnd* GetParentOwner() const;

 

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.

Call this member function to get the ActiveX control property specified by dwDispID.

void GetProperty(
    DISPID dwDispID,  
    VARTYPE vtProp,  
    void* pvProp)const;

 

Parameters

dwDispID
Identifies the property to be retrieved.

vtProp
Specifies the type of the property to be retrieved. For possible values, see the Remarks section for COleDispatchDriver::InvokeHelper.

pvProp
Address of the variable that will that will receive the property value. It must match the type specified by vtProp.

Remarks

GetProperty returns the value through pvProp.

System_CAPS_ICON_note.jpg Note

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

For more information about using this member function with ActiveX Control Containers, see the article ActiveX Control Containers: Programming ActiveX Controls in an ActiveX Control Container.

Gets a render target that is associated with this window.

CHwndRenderTarget* GetRenderTarget();

Return Value

Pointer to the render target or NULL.

Returns m_hWnd, or NULL if the this pointer is NULL.

HWND GetSafeHwnd() const;

 

Return Value

Returns the window handle for a window. Returns NULL if the CWnd is not attached to a window or if it is used with a NULL CWnd pointer.

Example

See the example for CWnd::SubclassWindow.

Call this member function to retrieve the owner window that should be used for dialog boxes or other modal windows.

static CWnd* GetSafeOwner(
    CWnd* pParent = NULL,  
    HWND* pWndTop = NULL);

Parameters

pParent
A pointer to a parent CWnd window. May be NULL.

pWndTop
A pointer to the window that is currently on top. May be NULL.

Return Value

A pointer to the safe owner for the given window.

Remarks

The safe owner is the first non-child parent window of pParent. If pParent is NULL, the thread's main window (retrieved via AfxGetMainWnd) is used to find an owner.

System_CAPS_ICON_note.jpg Note

The framework itself uses this function to determine the correct owner window for dialog boxes and property sheets where the owner is not specified.

Call this member function to obtain a pointer to the specified sibling scroll bar or splitter window.

virtual CScrollBar* GetScrollBarCtrl(int nBar) const;

 

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.

Retrieves information about the specified scroll bar.

BOOL GetScrollBarInfo(
    LONG idObject,  
    PSCROLLBARINFO psbi) const;

 

Parameters

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

psbi
Pointer to a SCROLLBARINFO structure that receives the information.

Return Value

Nonzero if the function succeeds; otherwise 0.

Remarks

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

Call this member function to retrieve the information that the SCROLLINFO structure maintains about a scroll bar.

BOOL GetScrollInfo(
    int nBar,  
    LPSCROLLINFO lpScrollInfo,  
    UINT nMask = SIF_ALL);

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.

  • SB_HORZ Retrieves the parameters for the window's standard horizontal scroll bar.

  • SB_VERT Retrieves the parameters for the window's standard vertical scroll bar.

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.

Call this member function to retrieve the maximum scrolling position of the scroll bar.

int GetScrollLimit(int nBar);

Parameters

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

  • SB_HORZ Retrieves the scroll limit of the horizontal scroll bar.

  • SB_VERT Retrieves the scroll limit of the vertical scroll bar.

Return Value

Specifies the maximum position of a scroll bar if successful; otherwise 0.

Retrieves the current position of the scroll box of a scroll bar.

int GetScrollPos(int nBar) const;

 

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.

Copies the current minimum and maximum scroll-bar positions for the given scroll bar to the locations specified by lpMinPos and lpMaxPos.

void GetScrollRange(
    int nBar,  
    LPINT lpMinPos,  
    LPINT lpMaxPos) const;

 

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.

lpMinPos
Points to the integer variable that is to receive the minimum position.

lpMaxPos
Points to the integer variable that is to receive the maximum position.

Remarks

If CWnd does not have a scroll bar, then the GetScrollRange member function copies 0 to lpMinPos and lpMaxPos.

The default range for a standard scroll bar is 0 to 100. The default range for a scroll-bar control is empty (both values are 0).

Returns the current window style.

DWORD GetStyle() const;

 

Return Value

The window's style. For more information about the window styles used in MFC, see Window Styles.

Allows the application to access the Control menu for copying and modification.

CMenu* GetSystemMenu(BOOL bRevert) const;

 

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

Retrieves information about the specified title bar.

BOOL GetTitleBarInfo(PTITLEBARINFO pti) const;

 

Parameters

pti
Pointer to a TITLEBARINFO structure that receives the information.

Remarks

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

Call this member function to retrieve the window's top level frame window, if any.

CFrameWnd* GetTopLevelFrame() const;

 

Return Value

Identifies the top-level frame window of the window.

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

Remarks

If CWnd has no attached window, or its top-level parent is not a CFrameWnd-derived object, this function returns NULL.

Call this member function to retrieve the top-level window.

CWnd* GetTopLevelOwner() const;

 

Return Value

Identifies the top-level window. The returned pointer may be temporary and should not be stored for later use.

Remarks

The top-level window is the window that is a child of the desktop. If CWnd has no attached window, this function returns NULL.

Call this member function to retrieve the window's top-level parent.

CWnd* GetTopLevelParent() const;

 

Return Value

Identifies the top-level parent window of the window.

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

Remarks

GetTopLevelParent is similar to GetTopLevelFrame and GetTopLevelOwner; however, it ignores the value set as the current owner window.

Searches for the top-level child window that belongs to CWnd.

CWnd* GetTopWindow() const;

 

Return Value

Identifies the top-level child window in a CWnd linked list of child windows. If no child windows exist, the value is NULL.

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

Remarks

If CWnd has no children, this function returns NULL.

Retrieves the coordinates of the smallest rectangle that completely encloses the update region.

BOOL GetUpdateRect(
    LPRECT lpRect,  
    BOOL bErase = FALSE);

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.

Retrieves the update region into a region identified by pRgn.

int GetUpdateRgn(
    CRgn* pRgn,  
    BOOL bErase = FALSE);

Parameters

pRgn
Identifies the update region.

bErase
Specifies whether the background will be erased and nonclient areas of child windows will be drawn. If the value is FALSE, no drawing is done.

Return Value

Specifies a short-integer flag that indicates the type of resulting region. The value can take any one of the following:

  • SIMPLEREGION The region has no overlapping borders.

  • COMPLEXREGION The region has overlapping borders.

  • NULLREGION The region is empty.

  • ERROR No region was created.

Remarks

The coordinates of this region are relative to the upper-left corner (client coordinates).

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

Returns a pointer to the window requested, or NULL if none.

CWnd* GetWindow(UINT nCmd) const;

 

Parameters

nCmd
Specifies the relationship between CWnd and the returned window. It can take one of the following values:

  • GW_CHILD Identifies the CWnd first child window.

  • GW_HWNDFIRST If CWnd is a child window, returns the first sibling window. Otherwise, it returns the first top-level window in the list.

  • GW_HWNDLAST If CWnd is a child window, returns the last sibling window. Otherwise, it returns the last top-level window in the list.

  • GW_HWNDNEXT Returns the next window on the window manager's list.

  • GW_HWNDPREV Returns the previous window on the window manager's list.

  • GW_OWNER Identifies the CWnd owner.

Return Value

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

Call this member function to retrieve the help context identifier, if any, associated with the window.

DWORD GetWindowContextHelpId() const;

 

Return Value

The help context identifier. Returns 0 if the window has none.

Call this member function to retrieve the number of associated child windows.

long GetWindowedChildCount();

Return Value

The number of child windows associated with the CWnd object.

Retrieves the display context for the entire window, including caption bar, menus, and scroll bars.

CDC* GetWindowDC();

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.

Retrieves information about the window.

BOOL GetWindowInfo(PWINDOWINFO pwi) const;

 

Parameters

pwi
A pointer to a WINDOWINFO structure.

Remarks

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

Retrieves the number of associated windowless child windows.

long GetWindowlessChildCount();

Return Value

The number of windowless child windows associated with the CWnd object.

Retrieves the show state and the normal (restored), minimized, and maximized positions of a window.

BOOL GetWindowPlacement(WINDOWPLACEMENT* lpwndpl) const;

 

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.

Copies the dimensions of the bounding rectangle of the CWnd object to the structure pointed to by lpRect.

void GetWindowRect(LPRECT lpRect) const;

 

Parameters

lpRect
Points to a CRect object or a RECT structure that will receive the screen coordinates of the upper-left and lower-right corners.

Remarks

The dimensions are given in screen coordinates relative to the upper-left corner of the display screen. The dimensions of the caption, border, and scroll bars, if present, are included.

Call this member function to get the window region of a window.

int GetWindowRgn(HRGN hRgn)const;

 

Parameters

hRgn
A handle to a window region.

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.

To set the window region of a window, call CWnd::SetWindowRgn.

Copies the CWnd caption title (if it has one) into the buffer pointed to by lpszStringBuf or into the destination string rString.

int GetWindowText(
    LPTSTR lpszStringBuf,  
    int nMaxCount) const;

 
 
void GetWindowText(
    CString& rString) const;

 

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.

Example

See the example for CWnd::SetWindowText.

Returns the length of the CWnd object caption title.

int GetWindowTextLength() const;

 

Return Value

Specifies the text length in characters, not including any null-termination character. The value is 0 if no such text exists.

Remarks

If CWnd is a control, the GetWindowTextLength member function returns the length of the text within the control instead of the caption.

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

Example

See the example for CWnd::SetWindowText.

Hides the caret by removing it from the display screen.

void HideCaret();

Remarks

Although the caret is no longer visible, it can be displayed again by using the ShowCaret member function. Hiding the caret does not destroy its current shape.

Hiding is cumulative. If HideCaret has been called five times in a row, the ShowCaret member function must be called five times before the caret will be shown.

Highlights or removes the highlight from a top-level (menu-bar) menu item.

BOOL HiliteMenuItem(
    CMenu* pMenu,  
    UINT nIDHiliteItem,  
    UINT nHilite);

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.

Call this member function to invoke the HTMLHelp application.

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

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

See CWinApp::HtmlHelp for more information.

Called by the framework to initialize dynamic layout for a window.

void InitDynamicLayout();

Remarks

Do not call this method directly.

Invalidates the entire client area of CWnd.

void Invalidate(BOOL bErase = TRUE);

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.

Example

See the example for CWnd::UpdateWindow.

Invalidates the client area within the given rectangle by adding that rectangle to the CWnd update region.

void InvalidateRect(
    LPCRECT lpRect,  
    BOOL bErase = TRUE);

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.

Invalidates the client area within the given region by adding it to the current update region of CWnd.

void InvalidateRgn(
    CRgn* pRgn,  
    BOOL bErase = TRUE);

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.

Call this member function to invoke the ActiveX Control method or property specified by dwDispID, in the context specified by wFlags.

void AFX_CDECL InvokeHelper(
    DISPID dwDispID,  
    WORD wFlags,  
    VARTYPE vtRet,  
    void* pvRet,  
    const BYTE* pbParamInfo,  
 ...);

Parameters

dwDispID
Identifies the method or property to be invoked.

wFlags
Flags describing the context of the call to IDispatch::Invoke.

vtRet
Specifies the type of the return value. For possible values, see the Remarks section for COleDispatchDriver::InvokeHelper.

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.

System_CAPS_ICON_note.jpg Note

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

For more information about using this member function with ActiveX Control Containers, see the article ActiveX Control Containers: Programming ActiveX Controls in an ActiveX Control Container.

Indicates whether the window specified by pWnd is a child window or other direct descendant of CWnd.

BOOL IsChild(const CWnd* pWnd) const;

 

Parameters

pWnd
Identifies the window to be tested.

Return Value

Specifies the outcome of the function. The value is nonzero if the window identified by pWnd is a child window of CWnd; otherwise 0.

Remarks

A child window is the direct descendant of CWnd if the CWnd object is in the chain of parent windows that leads from the original pop-up window to the child window.

Determines whether D2D support is enabled.

BOOL IsD2DSupportEnabled();

Return Value

TRUE if the feature is enabled; otherwise FALSE.

Call this member function to determine whether the given message is intended for a modeless dialog box; if it is, this function processes the message.

BOOL IsDialogMessage(LPMSG lpMsg);

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 :

BOOL CAboutDlg::PreTranslateMessage(MSG* pMsg)
{
   if(IsDialogMessage(pMsg))
      return TRUE;
   else
      return CDialog::PreTranslateMessage(pMsg);
}

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.

Determines whether a button control has a check mark next to it.

UINT IsDlgButtonChecked(int nIDButton) const;

 

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.

Determines whether dynamic layout is enabled on this window. If dynamic layout is enabled, the position and size of child windows can change when the user resizes the parent window.

BOOL IsDynamicLayoutEnabled() const;

 

Return Value

TRUE if dynamic layout is enabled; otherwise FALSE.

Remarks

Specifies whether CWnd is minimized (iconic).

BOOL IsIconic() const;

 

Return Value

Nonzero if CWnd is minimized; otherwise 0.

Example

void CAboutDlg::OnPaint()
{
   // This code, normally emitted by the Application Wizard for a dialog-
   // based project for the dialog's WM_PAINT handler, runs only if the 
   // window is iconic. The window erases the icon's area, then
   // paints the icon referenced by m_hIcon.
   if (IsIconic())
   {
      CPaintDC dc(this); // device context for painting

      SendMessage(WM_ICONERASEBKGND, (WPARAM)dc.GetSafeHdc(), 0);

      // Center icon in client rectangle
      int cxIcon = GetSystemMetrics(SM_CXICON);
      int cyIcon = GetSystemMetrics(SM_CYICON);
      CRect rect;
      GetClientRect(&rect);
      int x = (rect.Width() - cxIcon + 1) / 2;
      int y = (rect.Height() - cyIcon + 1) / 2;

      // Draw the icon
      dc.DrawIcon(x, y, m_hIcon);
   }
   else
   {
      CDialog::OnPaint();   
   }
}

Specifies whether CWnd has touch support.

BOOL IsTouchWindow() const;

 

Return Value

TRUE if CWnd has touch support; otherwise FALSE.

Remarks

Specifies whether CWnd is enabled for mouse and keyboard input.

BOOL IsWindowEnabled() const;

 

Return Value

Nonzero if CWnd is enabled; otherwise 0.

Example

//change the background color of an edit control on the dialog
HBRUSH CMyDlg::OnCtlColor(CDC* pDC, CWnd* pWnd, UINT nCtlColor)
{
   HBRUSH hbr = CDialog::OnCtlColor(pDC, pWnd, nCtlColor);

   if (pWnd->GetDlgCtrlID() == IDC_MYEDIT)
   {
      if (pWnd->IsWindowEnabled())
      {
         // Red brush for the background...
         pDC->SetBkColor(RGB(255, 0, 0));
         // m_pRedBrush is the CBrush object initialized with a red brush 
         // using CreateSolidBrush
         return(HBRUSH)m_RedBrush.GetSafeHandle();
      }
      else
      {
         // Blue brush for the background...
         pDC->SetBkColor(RGB(0, 0, 255));
         // m_pBlueBrush is the CBrush object initialized with a blue 
         // brush using CreateSolidBrush
         return (HBRUSH)m_BlueBrush.GetSafeHandle();
      }
   }

   return hbr;
}

Determines the visibility state of the given window.

BOOL IsWindowVisible() const;

 

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);
   }
}

Determines whether CWnd has been maximized.

BOOL IsZoomed() const;

 

Return Value

Nonzero if CWnd is maximized; otherwise 0.

Kills the timer event identified by nIDEvent from the earlier call to SetTimer.

BOOL KillTimer(UINT_PTR nIDEvent);

Parameters

nIDEvent
The value of the timer event passed to SetTimer.

Return Value

Specifies the outcome of the function. The value is nonzero if the event was killed. It is 0 if the KillTimer member function could not find the specified timer event.

Remarks

Pending WM_TIMER messages associated with the timer are not removed from the message queue.

Example

See the example for CWnd::SetTimer.

Called by the framework to load dynamic layout information from the resource file.

BOOL LoadDynamicLayoutResource(LPCTSTR lpszResourceName);

Parameters

lpszResourceName
The name of the resource that contains the desired dynamic layout information for this window.

Return Value

Nonzero if the function is successful. It is 0 if a failure occurs.

Remarks

Do not call this method directly.

Disables drawing in the given window.

BOOL LockWindowUpdate();

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.

The handle of the Windows window attached to this CWnd.

HWND m_hWnd;  

Remarks

The m_hWnd data member is a public variable of type HWND.

Converts (maps) a set of points from the coordinate space of the CWnd to the coordinate space of another window.

void MapWindowPoints(
    CWnd* pwndTo,  
    LPRECT lpRect) const;

 
 
void MapWindowPoints(
    CWnd* pwndTo,  
    LPPOINT lpPoint,  
    UINT nCount) const;

 

Parameters

pwndTo
Identifies the window to which points are converted. If this parameter is NULL, the points are converted to screen coordinates.

lpRect
Specifies the rectangle whose points are to be converted. The first version of this function is available only for Windows 3.1 and later.

lpPoint
A pointer to an array of POINT structure that contain the set of points to be converted.

nCount
Specifies the number of POINT structures in the array pointed to by lpPoint.

Creates and displays a window that contains an application-supplied message and caption, plus a combination of the predefined icons and pushbuttons described in the Message-Box Styles list.

int MessageBox(
    LPCTSTR lpszText,  
    LPCTSTR lpszCaption = NULL,  
    UINT nType = MB_OK);

Parameters

lpszText
Points to a CString object or null-terminated string containing the message to be displayed.

lpszCaption
Points to a CString object or null-terminated string to be used for the message-box caption. If lpszCaption is NULL, the default caption "Error" is used.

nType
Specifies the contents and behavior of the message box.

Return Value

This method utilizes the MessageBox function as defined in the Windows SDK. This method returns the result of calling this function.

Remarks

Use the global function AfxMessageBox instead of this member function to implement a message box in your application.

The following shows the various system icons that can be used in a message box:

Stop (x) iconMB_ICONHAND, MB_ICONSTOP, and MB_ICONERROR
Help () iconMB_ICONQUESTION
Important (!) iconMB_ICONEXCLAMATION and MB_ICONWARNING
Information (i) iconMB_ICONASTERISK and MB_ICONINFORMATION

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);
}

Call this member function to modify a window's style.

BOOL ModifyStyle(
    DWORD dwRemove,  
    DWORD dwAdd,  
    UINT nFlags = 0);

Parameters

dwRemove
Specifies window styles to be removed during style modification.

dwAdd
Specifies window 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 Window Styles and CreateWindow in the Windows SDK for information about the available window styles.

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

  • SWP_NOSIZE Retains the current size.

  • SWP_NOMOVE Retains the current position.

  • SWP_NOZORDER Retains the current Z order.

  • SWP_NOACTIVATE Does not activate the window.

To modify a window's extended styles, see ModifyStyleEx.

System_CAPS_ICON_note.jpg Note

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

Example

// This example adds the WS_CLIPCHILDREN style to the window.
// No Styles are removed from the window.
void CMyView::OnInitialUpdate()
{
   CView::OnInitialUpdate();
   ModifyStyle(0, WS_CLIPCHILDREN);
}

Call this member function to modify a window's extended style.

BOOL ModifyStyleEx(
    DWORD dwRemove,  
    DWORD dwAdd,  
    UINT nFlags = 0);

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:

  • SWP_NOSIZE Retains the current size.

  • SWP_NOMOVE Retains the current position.

  • SWP_NOZORDER Retains the current Z order.

  • SWP_NOACTIVATE Does not activate the window.

To modify windows using regular window styles, see ModifyStyle.

Example

// This example would make the dialog box transparent by
// changing the dialog window's extended styles.
int CAboutDlg::OnCreate(LPCREATESTRUCT lpCreateStruct)
{
   if (CDialog::OnCreate(lpCreateStruct) == -1)
      return -1;

   ModifyStyleEx(0, WS_EX_TRANSPARENT);   
   
   return 0;
}

Changes the position and dimensions.

void MoveWindow(
    int x,  
    int y,  
    int nWidth,  
    int nHeight,  
    BOOL bRepaint = TRUE);

 
void MoveWindow(
    LPCRECT lpRect,
    BOOL bRepaint = TRUE);

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.

lpRect
The CRect object or RECT structure that specifies the new size and position.

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.

Example

See the example for CWnd::ClientToScreen.

Signals the system that a predefined event occurred. If any client applications have registered a hook function for the event, the system calls the client's hook function.

void NotifyWinEvent(
    DWORD event,  
    LONG idObjectType,  
    LONG idObject);

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.

The framework calls this member function when a CWnd object is being activated or deactivated.

afx_msg void OnActivate(
    UINT nState,  
    CWnd* pWndOther,  
    BOOL bMinimized);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function to all top-level windows of the task being activated and for all top-level windows of the task being deactivated.

afx_msg void OnActivateApp(
    BOOL bActive,  
    DWORD dwThreadID);

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

System_CAPS_ICON_note.jpg 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 framework calls this member function to obtain ambient property values from a window that contains OLE controls.

virtual BOOL OnAmbientProperty(
    COleControlSite* pSite,  
    DISPID dispid,  
    VARIANT* pvar);

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.

afx_msg void OnAppCommand(
    CWnd* pWnd,  
    UINT nCmd,  
    UINT nDevice,  
    UINT nKey);

Parameters

ParameterDescription
[in] pWndPointer 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] nCmdIndicates the application command. For a list of possible values, see the commands under the cmd section of the lParam parameter of WM_APPCOMMAND.
[in] nDeviceThe 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] nKeyIndicates 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the Clipboard contains a data handle for the CF_OWNERDISPLAY format (that is, when the Clipboard owner will display the Clipboard contents).

afx_msg void OnAskCbFormatName(
    UINT nMaxCount,  
    LPTSTR lpszString);

Parameters

nMaxCount
Specifies the maximum number of bytes to copy.

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function to inform CWnd to cancel any internal mode.

afx_msg void OnCancelMode();

Remarks

If the CWnd object has the focus, its OnCancelMode member function is called when a dialog box or message box is displayed. This gives the CWnd the opportunity to cancel modes such as mouse capture.

The default implementation responds by calling the ReleaseCapture Windows function. Override this member function in your derived class to handle other modes.

The framework calls this member function to notify the window that is losing the mouse capture.

afx_msg void OnCaptureChanged(CWnd* pWnd);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function for each window in the Clipboard-viewer chain to notify it that a window is being removed from the chain.

afx_msg void OnChangeCbChain(
    HWND hWndRemove,  
    HWND hWndAfter);

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.

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

Called when the user interface (UI) state should be changed.

afx_msg void OnChangeUIState(
    UINT nAction,  
    UINT nUIElement);

Parameters

nAction
Specifies the action to be taken. Can be one of the following values:

  • UIS_CLEAR The UI state element (specified by nUIElement) should be hidden.

  • UIS_INITIALIZE The UI state element (specified by nUIElement) should be changed based on the last input event. For more information, see the Remarks section of WM_CHANGEUISTATE.

  • UIS_SET The UI state element (specified by nUIElement) should be visible.

nUIElement
Specifies which UI state elements are affected or the style of the control. Can be one of the following values:

  • UISF_HIDEACCEL Keyboard accelerators.

  • UISF_HIDEFOCUS Focus indicators.

  • UISF_ACTIVE Windows XP: A control should be drawn in the style used for active controls.

Remarks

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

The framework calls this member function when a keystroke translates to a nonsystem character.

afx_msg void OnChar(
    UINT nChar,  
    UINT nRepCnt,  
    UINT nFlags);

Parameters

nChar
Contains the character code value of the key.

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:

ValueMeaning
0-15Specifies 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-23Specifies the scan code. The value depends on the original equipment manufacturer (OEM)
24Specifies 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-28Used internally by Windows.
29Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30Specifies 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.
31Specifies 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.

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

Called when a list box with the LBS_WANTKEYBOARDINPUT style sends its owner a WM_CHARTOITEM message in response to a WM_CHAR message.

afx_msg int OnCharToItem(
    UINT nChar,  
    CListBox* pListBox,  
    UINT nIndex);

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

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

afx_msg void OnChildActivate();

This member function is called by this window's parent window when it receives a notification message that applies to this window.

virtual BOOL OnChildNotify(
    UINT message,  
    WPARAM wParam,  
    LPARAM lParam,  
    LRESULT* pResult);

Parameters

message
A Windows message number sent to a parent window.

wParam
The wparam associated with the message.

lParam
The lparam associated with the message.

pLResult
A pointer to a value to be returned from the parent's window procedure. This pointer will be NULL if no return value is expected.

Return Value

Nonzero if this window is responsible for handling the message sent to its parent; otherwise 0.

Remarks

Never call this member function directly.

The default implementation of this member function returns 0, which means that the parent should handle the message.

Override this member function to extend the manner in which a control responds to notification messages.

The framework calls this member function when the contents of the clipboard have changed.

afx_msg void OnClipboardUpdate();

The framework calls this member function as a signal that the CWnd or an application is to terminate.

afx_msg void OnClose();

Remarks

The default implementation calls DestroyWindow.

The framework calls this member when the rendering policy for the nonclient area has changed.

afx_msg void OnColorizationColorChanged(
    DWORD dwColorizationColor,   
    BOOL bOpacity);

Parameters

ParameterDescription
[in] dwColorizationColorSpecifies 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] bOpacitytrue if the new color is blended with opacity; false if it is not.

Remarks

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user selects an item from a menu, when a child control sends a notification message, or when an accelerator keystroke is translated.

virtual BOOL OnCommand(
    WPARAM wParam,  
    LPARAM lParam);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function for all top-level windows when Windows detects that more than 12.5 percent of system time over a 30- to 60-second interval is being spent compacting memory.

afx_msg void OnCompacting(UINT nCpuTime);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function to specify the relative position of a new item in a child sorted owner-draw combo or list box.

afx_msg int OnCompareItem(
    int nIDCtl,  
    LPCOMPAREITEMSTRUCT lpCompareItemStruct);

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:

ValueMeaning
–1Item 1 sorts before item 2.
0Item 1 and item 2 sort the same.
1Item 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function for all top-level windows when the Desktop Window Manager (DWM) composition is enabled or disabled.

afx_msg void OnCompositionChanged();

Remarks

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

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

Called by the framework when the user has clicked the right mouse button (right clicked) in the window.

afx_msg void OnContextMenu(
    CWnd* pWnd,  
    CPoint pos);

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.

This member function is called by the framework to copy data from one application to another.

afx_msg BOOL OnCopyData(
    CWnd* pWnd,  
    COPYDATASTRUCT* pCopyDataStruct);

Parameters

pWnd
A pointer to a CWnd object that is sending the data.

pCopyDataStruct
A pointer to a COPYDATASTRUCT structure that contains the data being sent.

Return Value

Returns TRUE if the receiving application successfully accepts the data. Otherwise, returns FALSE.

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when an application requests that the Windows window be created by calling the Create or CreateEx member function.

afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when a child control is about to be drawn.

afx_msg HBRUSH OnCtlColor(
    CDC* pDC,  
    CWnd* pWnd,  
    UINT nCtlColor);

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.

System_CAPS_ICON_note.jpg 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;
}

The framework calls this member function when the OnKeyUp member function and the OnKeyDown member functions are called.

afx_msg void OnDeadChar(
    UINT nChar,  
    UINT nRepCnt,  
    UINT nFlags);

Parameters

nChar
Specifies the dead-key character value.

nRepCnt
Specifies the repeat count.

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

ValueDescription
0–7Scan code (OEM-dependent value). Low byte of high-order word.
8Extended key, such as a function key or a key on the numeric keypad (1 if it is an extended key; otherwise 0).
9–10Not used.
11–12Used internally by Windows.
13Context code (1 if the ALT key is held down while the key is pressed; otherwise 0).
14Previous key state (1 if the key is down before the call, 0 if the key is up).
15Transition 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function to inform the owner of an owner-draw list box or combo box that the list box or combo box is destroyed or that items have been removed by CComboBox::DeleteString, CListBox::DeleteString, CComboBox::ResetContent, or CListBox::ResetContent.

afx_msg void OnDeleteItem(
    int nIDCtl,  
    LPDELETEITEMSTRUCT lpDeleteItemStruct);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function to inform the CWnd object that it is being destroyed.

afx_msg void OnDestroy();

Remarks

OnDestroy is called after the CWnd object is removed from the screen.

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.

The framework calls this member function for the Clipboard owner when the Clipboard is emptied through a call to the EmptyClipboard Windows function.

afx_msg void OnDestroyClipboard();

The framework calls this member function to notify an application or device driver of a change to the hardware configuration of a device or the computer.

afx_msg BOOL OnDeviceChange(
    UINT nEventType,  
    DWORD_PTR dwData);

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.

The nEvent parameter can be one of these values:

System_CAPS_ICON_note.jpg 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 framework calls this member function for all top-level CWnd objects when the user changes device-mode settings.

afx_msg void OnDevModeChange(LPTSTR lpDeviceName);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function for each window in the Clipboard-viewer chain when the contents of the Clipboard change.

afx_msg void OnDrawClipboard();

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.

Called by the framework when it needs to obtain a bitmap to be displayed on Windows 7 tab thumbnail, or on the client for application peek.

virtual void OnDrawIconicThumbnailOrLivePreview(
    CDC& dc,  
    CRect rect,  
    CSize szRequiredThumbnailSize,  
    BOOL bIsThumbnail,  
    BOOL& bAlphaChannelSet);

Parameters

dc
Specifies the device context.

rect
Specifies the bounding rectangle of the area to render.

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.

The framework calls this member function for the owner of an owner-draw button control, combo-box control, list-box control, or menu when a visual aspect of the control or menu has changed.

afx_msg void OnDrawItem(
    int nIDCtl,  
    LPDRAWITEMSTRUCT lpDrawItemStruct);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user releases the left mouse button over a window that has registered itself as the recipient of dropped files.

afx_msg void OnDropFiles(HDROP hDropInfo);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when an application changes the enabled state of the CWnd object.

afx_msg void OnEnable(BOOL bEnable);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function after the CWnd object has returned a nonzero value from a OnQueryEndSession member function call.

afx_msg void OnEndSession(BOOL bEnding);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function to inform an application's main window procedure that a modal dialog box or a menu is entering an idle state.

afx_msg void OnEnterIdle(
    UINT nWhy,  
    CWnd* pWho);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when a menu modal loop has been entered.

afx_msg void OnEnterMenuLoop(BOOL bIsTrackPopupMenu);

Parameters

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

Remarks

System_CAPS_ICON_note.jpg 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 framework calls this member function one time after the affected window enters a moving or sizing modal loop.

afx_msg void OnEnterSizeMove();

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the CWnd object background needs erasing (for example, when resized).

afx_msg BOOL OnEraseBkgnd(CDC* pDC);

Parameters

pDC
Specifies the device-context object.

Return Value

Nonzero if it erases the background; otherwise 0.

Remarks

It is called to prepare an invalidated region for painting.

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when a menu modal loop has been exited.

afx_msg void OnExitMenuLoop(BOOL bIsTrackPopupMenu);

Parameters

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

Remarks

System_CAPS_ICON_note.jpg 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 framework calls this member function one time after the affected window exits a moving or sizing modal loop.

afx_msg void OnExitSizeMove();

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.

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

All top-level windows in the system receive an OnFontChange call from the framework after the application changes the pool of font resources.

afx_msg void OnFontChange();

Remarks

An application that adds or removes fonts from the system (for example, through the AddFontResource or RemoveFontResource Windows function) should send the WM_FONTCHANGE message to all top-level windows.

To send this message, use the SendMessage Windows function with the hWnd parameter set to HWND_BROADCAST.

Called for a control so the control can process arrow-key and TAB-key input itself.

afx_msg UINT OnGetDlgCode();

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

The framework calls this member function whenever Windows needs to know the maximized position or dimensions, or the minimum or maximum tracking size.

afx_msg void OnGetMinMaxInfo(MINMAXINFO* lpMMI);

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.

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

Handles F1 Help within the application (using the current context).

afx_msg void OnHelp();

Remarks

See CWinApp::OnHelp for more information.

Handles the ID_HELP_FINDER and ID_DEFAULT_HELP commands.

afx_msg void OnHelpFinder();

Remarks

See CWinApp::OnHelpFinder for more information.

Handles the ID_HELP_INDEX command and provides a default Help topic.

afx_msg void OnHelpIndex();

Remarks

See CWinApp::OnHelpIndex for more information.

Called by the framework when the user presses the F1 key.

afx_msg BOOL OnHelpInfo(HELPINFO* lpHelpInfo);

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.

Handles the ID_HELP_USING command.

afx_msg void OnHelpUsing();

Remarks

See CWinApp::OnHelpUsing for more information.

The framework calls this member function when the user presses a system-wide hot key.

afx_msg void OnHotKey(
    UINT nHotKeyId,   
    UINT nKey1,   
    UINT nKey2);

Parameters

ParameterDescription
[in] nHotKeyIdIdentifier for the hot key that generated the message. If the message was generated by a system-defined hot key, this parameter will be one of the following values:

- IDHOT_SNAPDESKTOP - The snap desktop hot key was pressed.
- IDHOT_SNAPWINDOW - The snap window hot key was pressed.
[in] nKey1A 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] nKey2The 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user clicks a window's horizontal scroll bar.

afx_msg void OnHScroll(
    UINT nSBCode,  
    UINT nPos,  
    CScrollBar* pScrollBar);

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.

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

Example

void CMdiView::OnHScroll(UINT nSBCode, UINT nPos, CScrollBar* pScrollBar)
{
   // Get the minimum and maximum scroll-bar positions.
   int minpos;
   int maxpos;
   GetScrollRange(SB_HORZ, &minpos, &maxpos); 
   maxpos = GetScrollLimit(SB_HORZ);

   // Get the current position of scroll box.
   int curpos = GetScrollPos(SB_HORZ);

   // Determine the new position of scroll box.
   switch (nSBCode)
   {
   case SB_LEFT:      // Scroll to far left.
      curpos = minpos;
      break;

   case SB_RIGHT:      // Scroll to far right.
      curpos = maxpos;
      break;

   case SB_ENDSCROLL:   // End scroll.
      break;

   case SB_LINELEFT:      // Scroll left.
      if (curpos > minpos)
         curpos--;
      break;

   case SB_LINERIGHT:   // Scroll right.
      if (curpos < maxpos)
         curpos++;
      break;

   case SB_PAGELEFT:    // Scroll one page left.
   {
      // Get the page size. 
      SCROLLINFO   info;
      GetScrollInfo(SB_HORZ, &info, SIF_ALL);
   
      if (curpos > minpos)
      curpos = max(minpos, curpos - (int) info.nPage);
   }
      break;

   case SB_PAGERIGHT:      // Scroll one page right.
   {
      // Get the page size. 
      SCROLLINFO   info;
      GetScrollInfo(SB_HORZ, &info, SIF_ALL);

      if (curpos < maxpos)
         curpos = min(maxpos, curpos + (int) info.nPage);
   }
      break;

   case SB_THUMBPOSITION: // Scroll to absolute position. nPos is the position
      curpos = nPos;      // of the scroll box at the end of the drag operation.
      break;

   case SB_THUMBTRACK:   // Drag scroll box to specified position. nPos is the
      curpos = nPos;     // position that the scroll box has been dragged to.
      break;
   }

   // Set the new position of the thumb (scroll box).
   SetScrollPos(SB_HORZ, curpos);

   CView::OnHScroll(nSBCode, nPos, pScrollBar);
}

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.

afx_msg void OnHScrollClipboard(
    CWnd* pClipAppWnd,  
    UINT nSBCode,  
    UINT nPos);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function for a minimized (iconic) CWnd object when the background of the icon must be filled before painting the icon.

afx_msg void OnIconEraseBkgnd(CDC* pDC);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when a menu is about to become active.

afx_msg void OnInitMenu(CMenu* pMenu);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when a pop-up menu is about to become active.

afx_msg void OnInitMenuPopup(
    CMenu* pPopupMenu,  
    UINT nIndex,  
    BOOL bSysMenu);

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.

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when an I/O device is added or removed from the system.

afx_msg void OnInputDeviceChange(unsigned short uFlag);

Parameters

ParameterDescription
[in] uFlagThis flag can contain the following values:

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

System_CAPS_ICON_note.jpg 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 framework calls this member for the topmost affected window after an application's input language has been changed.

afx_msg void OnInputLangChange(
    UINT nCharSet,   
    UINT nLocaleId);

Parameters

ParameterDescription
[in] nCharSetThe character set of the new locale. For more information, see the lfCharSet parameter of the LOGFONT structure.
[in] nLocaleIdThe input locale identifier. For more information, see Language Identifier Constants and Strings.

Remarks

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

System_CAPS_ICON_note.jpg 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 framework calls this member for window with the focus when the user chooses a new input language.

afx_msg void OnInputLangChangeRequest(
    UINT nFlags,   
    UINT nLocaleId);

Parameters

ParameterDescription
[in] nFlagsA 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.
[in] nLocaleIdThe input locale identifier. For more information, see Language Identifier Constants and Strings.

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when a nonsystem key is pressed.

afx_msg void OnKeyDown(
    UINT nChar,  
    UINT nRepCnt,  
    UINT nFlags);

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:

ValueDescription
0–7Scan code (OEM-dependent value).
8Extended key, such as a function key or a key on the numeric keypad (1 if it is an extended key).
9–10Not used.
11–12Used internally by Windows.
13Context code (1 if the ALT key is held down while the key is pressed; otherwise 0).
14Previous key state (1 if the key is down before the call, 0 if the key is up).
15Transition 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when a nonsystem key is released.

afx_msg void OnKeyUp(
    UINT nChar,  
    UINT nRepCnt,  
    UINT nFlags);

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:

ValueDescription
0–7Scan code (OEM-dependent value). Low byte of high-order word.
8Extended key, such as a function key or a key on the numeric keypad (1 if it is an extended key; otherwise 0).
9–10Not used.
11–12Used internally by Windows.
13Context code (1 if the ALT key is held down while the key is pressed; otherwise 0).
14Previous key state (1 if the key is down before the call, 0 if the key is up).
15Transition 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function immediately before losing the input focus.

afx_msg void OnKillFocus(CWnd* pNewWnd);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user double-clicks the left mouse button.

afx_msg void OnLButtonDblClk(
    UINT nFlags,  
    CPoint point);

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user presses the left mouse button.

afx_msg void OnLButtonDown(
    UINT nFlags,  
    CPoint point);

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user releases the left mouse button.

afx_msg void OnLButtonUp(
    UINT nFlags,  
    CPoint point);

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user double-clicks the middle mouse button.

afx_msg void OnMButtonDblClk(
    UINT nFlags,  
    CPoint point);

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user presses the middle mouse button.

afx_msg void OnMButtonDown(
    UINT nFlags,  
    CPoint point);

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user releases the middle mouse button.

afx_msg void OnMButtonUp(
    UINT nFlags,  
    CPoint point);

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

System_CAPS_ICON_note.jpg 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 framework calls this member function for the child window being deactivated and the child window being activated.

afx_msg void OnMDIActivate(
    BOOL bActivate,  
    CWnd* pActivateWnd,  
    CWnd* pDeactivateWnd);

Parameters

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

System_CAPS_ICON_note.jpg 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 framework calls this member function by the framework for the owner of an owner-draw button, combo box, list box, or menu item when the control is created.

afx_msg void OnMeasureItem(
    int nIDCtl, LPMEASUREITEMSTRUCT lpMeasureItemStruct);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user presses a menu mnemonic character that doesn't match any of the predefined mnemonics in the current menu.

afx_msg LRESULT OnMenuChar(
    UINT nChar,  
    UINT nFlags,  
    CMenu* pMenu);

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:

ValueDescription
0Tells Windows to discard the character that the user pressed and creates a short beep on the system speaker.
1Tells Windows to close the current menu.
2Informs 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function of the current drag-and-drop menu when the user begins to drag a menu item.

afx_msg UINT OnMenuDrag(
    UINT nPos,   
    CMenu* pMenu);

Parameters

ParameterDescription
[in] nPosThe index position of the menu item when the drag operation begins.
[in] pMenuPointer to the CMenu object that contains the menu item.

Return Value

Return ValueMeaning
MND_CONTINUEThe menu should remain active. If the mouse is released, it should be ignored.
MND_ENDMENUThe menu should be ended.

Remarks

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

System_CAPS_ICON_note.jpg 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 framework calls this member function of the current drag-and-drop menu when the mouse cursor enters a menu item or moves from the center of the item to the top or bottom of the item.

afx_msg UINT OnMenuGetObject(MENUGETOBJECTINFO* pMenuGetObjectInfo);

Parameters

ParameterDescription
[in] pMenuPointer to a MENUGETOBJECTINFO structure that contains information about the drag-and-drop menu the mouse cursor is on.

Return Value

Return ValueMeaning
MNGO_NOERRORAn 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_NOINTERFACENo drop-and-drag interface is supported.

Remarks

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the user releases the right mouse button while the cursor is on a menu item.

afx_msg void OnMenuRButtonUp(
    UINT nPos,  
    CMenu* pMenu);

Parameters

ParameterDescription
[in] nPosThe index position of the menu item when the right mouse button was released.
[in] pMenuPointer to the CMenu object that contains the menu item.

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.

System_CAPS_ICON_note.jpg 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 associated with a menu, OnMenuSelect is called by the framework when the user selects a menu item.

afx_msg void OnMenuSelect(
    UINT nItemID,  
    UINT nFlags,  
    HMENU hSysMenu);

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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the cursor is in an inactive window and the user presses a mouse button.

afx_msg int OnMouseActivate(
    CWnd* pDesktopWnd,  
    UINT nHitTest,  
    UINT message);

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

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

Example

// The code fragment below shows how to UI activate an ActiveX control.
// CMyAxCtrl is a COleControl-derived class.
int CMyAxCtrl::OnMouseActivate(CWnd* pDesktopWnd, UINT nHitTest, UINT message)
{
   OnActivateInPlace(TRUE, NULL);  // OnActivateInPlace() is an undocumented function
   return COleControl::OnMouseActivate(pDesktopWnd, nHitTest, message);
}

The framework calls this member function when the cursor hovers over the client area of the window for the period of time specified in a prior call to TrackMouseEvent.

afx_msg void OnMouseHover(
    UINT nFlags,   
    CPoint point);

Parameters

ParameterDescription
[in] nFlagsA 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] pointA 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 KeyDescription
MK_CONTROLThe CTRL key is pressed.
MK_LBUTTONThe left mouse button is pressed.
MK_MBUTTONThe middle mouse button is pressed.
MK_RBUTTONThe right mouse button is pressed.
MK_SHIFTThe SHIFT key is pressed.
MK_XBUTTON1The XBUTTON1 mouse button of the Microsoft IntelliMouse is pressed.
MK_XBUTTON2The XBUTTON2 mouse button of the Microsoft IntelliMouse is pressed.
System_CAPS_ICON_note.jpg 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 framework calls this member when the current window is composed by the Desktop Window Manager (DWM), and that window is maximized.

afx_msg void OnMouseHWheel(
    UINT nFlags,   
    short zDelta,   
    CPoint pt);

Parameters

ParameterDescription
[in] nFlagsA 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.

For a list of flags, see the "Message Parameters" subheading in About Mouse Input.
[in] zDeltaIndicates 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] ptA 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.

System_CAPS_ICON_note.jpg 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 framework calls this member function when the cursor leaves the client area of the window specified in a prior call to TrackMouseEvent.

afx_msg void OnMouseLeave();

Remarks

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

System_CAPS_ICON_note.jpg 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 framework calls this member function when the mouse cursor moves.

afx_msg void OnMouseM