|
CDialog Class |
Description
CDialog adds support for dialogs to Win32++. Dialogs are specialised windows
which are a parent window for common controls. Common controls are special
window types such as buttons, edit controls, tree views, list views, static text
etc.
The layout of a dialog is typically defined in a resource script
file (often Resource.rc). While this script file can be constructed manually, it
is often created using a resource editor. If your compiler doesn't include a
resource editor, you might find ResEdit useful. It is a free resource editor
available for download at: http://www.resedit.net/
CDialog
supports modal and modeless dialogs. It supports the creation of dialogs
defined in a resource script file, as well as those defined in a dialog
template.
The Dialog sample program can be used as the starting point for
your own dialog applications.
Refer to the documentation that ships with the Microsoft Windows Software Development Kit for more information on the use of dialogs.
CDialog Members
Construction
| CDialog | CDialog(UINT nResID); CDialog(LPCTSTR lpszResName); CDialog(LPCDLGTEMPLATE lpTemplate);Constructor for CDialog. There are three forms of the CDialog constructor, one each for dialogs based on a resource ID, a resource string, and a dialog template. |
Overridables
| DialogProc | virtual BOOL DialogProc(UINT uMsg, WPARAM wParam, LPARAM lParam);The window procedure for this CDialog object. Override this function to specify how the messages for this window are to be handled. Return all unhandled messages to DialogProcDefault. |
| EndDialog | virtual void EndDialog(INT_PTR nResult);Ends a modal or modeless dialog. |
| OnCancel | virtual void OnCancel();Called when the Cancel button is pressed. |
| OnInitDialog | virtual BOOL OnInitDialog();Called when the dialog starts, before it is displayed. Override the function to specify what happens when the dialog is created. |
| OnOK | virtual void OnOK();Called when the OK button is pressed. The default behavior is to end the dialog when the OK button is pressed. |
| PreTranslateMessage | virtual BOOL PreTranslateMessage(MSG* pMsg);Override this function to filter mouse and keyboard messages prior to being passed to the message loop. |
Operations
| AttachItem | virtual void AttachItem(int nID, CWnd& Wnd);Attach a dialog item to a CWnd. |
| Create | virtual HWND Create(CWnd* pParent = NULL);Creates a modeless dialog. |
| DialogProcDefault | virtual BOOL DialogProcDefault(UINT uMsg, WPARAM wParam, LPARAM lParam);The default dialog procedure. All unhandled messages should be passed to this function. |
| DoModal | virtual INT_PTR DoModal(CWnd* pParent = NULL);Create a modal dialog. A modal dialog must be closed before the owner window can be made active. |
| DoModeless | virtual HWND DoModeless(CWnd* pParent = NULL);Create a modeless dialog. |
| GetDefID | DWORD GetDefID() const;Retrieves the identifier of the default push button control for the dialog. |
| GotoDlgCtrl | void GotoDlgCtrl(CWnd* pWndCtrl);Sets the keyboard focus to the specified control. |
| MapDialogRect | BOOL MapDialogRect(LPRECT pRect) const;Converts the dialog box units to screen units (pixels). |
| NextDlgCtrl | void NextDlgCtrl() const;Sets the keyboard focus to the next dialog control. |
| PrevDlgCtrl | void PrevDlgCtrl() const;Sets the keyboard focus to the previous dialog control. |
| SetDefID | void SetDefID(UINT nID);Changes the identifier of the default push button for a dialog box. |
State functions
| IsModal | BOOL IsModal() const;Returns TRUE of the dialog is modal. |
| IsIndirect | BOOL IsIndirect() const;Returns TRUE of the dialog is created from a dialog box template in memory. |
Base class Members
For base class members, refer to the members of CWnd.
Remarks
Modal dialogs are always the application's active window. While it is are running, the modal dialog is the only window that can accept user input for the application. Modeless dialogs, on the other hand, allow other windows to become active and accept user input while they are running.
Modal dialogs run their own internal message loop, whereas modeless dialogs run the message loop provided by CWinApp. While the modal dialog is running, its internal message loop processes all messages for the thread the dialog runs in, including those of other windows.
Dialogs are used to display various controls, such as buttons, TreeViews, ListViews, static text and so forth. Each of these controls is actually a child window of the dialog. The following function are often used to manage dialog controls:
- AttachDlgItem
- CheckDlgButton
- GetDlgItem
- GetDlgItemInt
- GetDlgItemText
- SendDlgMessage
- SetDlgItemInt
- SetDlgItemText
The AttachDlgItem function is used to attach a dialog control to CWnd derived object. This allows the CWnd derived object to handle the control's messages in WndProc, and the control's notifications in OnNotifyReflect.
A modeless dialog can be used as a view window for a frame, MDIChild, docker etc. The FormDemo sample demonstrate how to use a dialog as a view window in a CFrame. This sample also demonstrates how to use CResizer to automatically reposition the dialog's controls when the frame is resized.
Refer to the Dialog section for more information on how to use CDialog to create dialogs.
Summary Information
| Header file | dialog.h |
| Win32/64 support | Yes |
| WinCE support | Yes |