CDialogEx Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CDialogEx Class.

The CDialogEx class specifies the background color and background image of a dialog box.

Syntax

class CDialogEx : public CDialog  

Members

Public Constructors

Name	Description
CDialogEx::CDialogEx	Constructs a CDialogEx object.
CDialogEx::~CDialogEx	Destructor.

Public Methods

Name	Description
CDialogEx::SetBackgroundColor	Sets the background color of the dialog box.
CDialogEx::SetBackgroundImage	Sets the background image of the dialog box.

Remarks

To use the CDialogEx class, derive your dialog box class from the CDialogEx class instead of the CDialog class.

Dialog box images are stored in a resource file. The framework automatically deletes any image that is loaded from the resource file. To programmatically delete the current background image, call the CDialogEx::SetBackgroundImage method or implement an OnDestroy event handler. When you call the CDialogEx::SetBackgroundImage method, pass in an HBITMAP parameter as the image handle. The CDialogEx object will take ownership of the image and delete it if the m_bAutoDestroyBmp flag is TRUE.

A CDialogEx object can be a parent of a CMFCPopupMenu Class object. The CMFCPopupMenu Class object calls the CDialogEx::SetActiveMenu method when the CMFCPopupMenu Class object opens. Afterward, the CDialogEx object handles any menu event until the CMFCPopupMenu Class object is closed.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CDialog

CDialogEx

Requirements

Header: afxdialogex.h

CDialogEx::CDialogEx

Constructs a CDialogEx object.

CDialogEx(
    UINT nIDTemplate,  
    CWnd* pParent=NULL);

 
CDialogEx(
    LPCTSTR lpszTemplateName,  
    CWnd* pParentWnd=NULL);

Parameters

[in] nIDTemplate
The resource ID of a dialog box template.

[in] lpszTemplateName
The resource name of a dialog box template.

[in] pParent
A pointer to the parent window. The default value is NULL.

[in] pParentWnd
A pointer to the parent window. The default value is NULL.

Return Value

Remarks

CDialogEx::SetBackgroundColor

Sets the background color of the dialog box.

void SetBackgroundColor(
    COLORREF color,  
    BOOL bRepaint=TRUE);

Parameters

[in] color
An RGB color value.

[in] bRepaint
TRUE to immediately update the screen; otherwise, FALSE. The default value is TRUE.

Remarks

CDialogEx::SetBackgroundImage

Sets the background image of the dialog box.

void SetBackgroundImage(
    HBITMAP hBitmap,  
    BackgroundLocation location=BACKGR_TILE,  
    BOOL bAutoDestroy=TRUE,  
    BOOL bRepaint=TRUE);

 
BOOL SetBackgroundImage(
    UINT uiBmpResId,  
    BackgroundLocation location=BACKGR_TILE,  
    BOOL bRepaint=TRUE);

Parameters

[in] hBitmap
A handle to the background image.

[in] uiBmpResId
The resource ID of the background image.

[in] location
One of the CDialogEx::BackgroundLocation values that specify the location of the image. Valid values include BACKGR_TILE, BACKGR_TOPLEFT, BACKGR_TOPRIGHT, BACKGR_BOTTOMLEFT, and BACKGR_BOTTOMRIGHT. The default value is BACKGR_TILE.

[in] bAutoDestroy
TRUE to automatically destroy the background image; otherwise, FALSE.

[in] bRepaint
TRUE to immediately redraw the dialog box; otherwise, FALSE.

Return Value

In the second method overload syntax, TRUE if the method is successful; otherwise, FALSE.

Remarks

The image that you specify is not stretched to fit the dialog box client area.

See Also

Hierarchy Chart
Classes
CMFCPopupMenu Class
CContextMenuManager Class