CDialogEx Class

  • Article

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

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

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

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

pParentWnd
[in] 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

color
[in] An RGB color value.

bRepaint
[in] 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

hBitmap
[in] A handle to the background image.

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

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

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

bRepaint
[in] 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 isn't stretched to fit the dialog box client area.

See also

Hierarchy Chart
Classes
CMFCPopupMenu Class
CContextMenuManager Class