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.
class CDialogEx : public CDialog
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. |
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.
Header: afxdialogex.h
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
Sets the background color of the dialog box.
void SetBackgroundColor(
COLORREF color,
BOOL bRepaint=TRUE);
Parameters
[in] color
An RGB color value.
[in] bRepaintTRUE to immediately update the screen; otherwise, FALSE. The default value is TRUE.
Remarks
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] bAutoDestroyTRUE to automatically destroy the background image; otherwise, FALSE.
[in] bRepaintTRUE 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.
Hierarchy Chart
Classes
CMFCPopupMenu Class
CContextMenuManager Class