Standard Dialog Data Exchange Routines
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 Standard Dialog Data Exchange Routines.
This topic lists the standard dialog data exchange (DDX) routines used for common MFC dialog controls.
Note
The standard dialog data exchange routines are defined in the header file afxdd_.h. However, applications should include afxwin.h.
DDX Functions
| DDX_CBIndex | Initializes or retrieves the index of the current selection of a combo box control. |
| DDX_CBString | Initializes or retrieves the current contents of the edit field of a combo box control. |
| DDX_CBStringExact | Initializes or retrieves the current contents of the edit field of a combo box control. |
| DDX_Check | Initializes or retrieves the current state of a check box control. |
| DDX_Control | Subclasses a given control within a dialog box. |
| DDX_DateTimeCtrl | Initializes or retrieves date and/or time data of a date and time picker control. |
| DDX_IPAddress | Initializes or retrieves the current value of an IP address control. |
| DDX_LBIndex | Initializes or retrieves the index of the current selection of a list box control. |
| DDX_LBString | Initializes or retrieves the current selection within a list box control. |
| DDX_LBStringExact | Initializes or retrieves the current selection within a list box control. |
| DDX_MonthCalCtrl | Initializes or retrieves the current value of a month calendar control. |
| DDX_Radio | Initializes or retrieves the 0-based index of the radio control that is currently checked within a radio control group. |
| DDX_Scroll | Initializes or retrieves the current position of a scroll control's thumb. |
| DDX_Slider | Initializes or retrieves the current position of a slider control's thumb. |
| DDX_Text | Initializes or retrieves the current value of an edit control. |
DDX_CBIndex
The DDX_CBIndex function manages the transfer of int data between a combo box control in a dialog box, form view, or control view object and a int data member of the dialog box, form view, or control view object.
void AFXAPI DDX_CBIndex(
CDataExchange* pDX,
int nIDC,
int& index);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the combo box control associated with the control property.
index
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_CBIndex is called, index is set to the index of the current combo box selection. If no item is selected, index is set to 0.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_CBString
The DDX_CBString function manages the transfer of CString data between the edit control of a combo box control in a dialog box, form view, or control view object and a CString data member of the dialog box, form view, or control view object.
void AFXAPI DDX_CBString(
CDataExchange* pDX,
int nIDC,
CString& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the combo box control associated with the control property.
value
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_CBString is called, value is set to the current combo box selection. If no item is selected, value is set to a string of zero length.
Note
If the combo box is a drop-down list box, the value exchanged is limited to 255 characters.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_CBStringExact
The DDX_CBStringExact function manages the transfer of CString data between the edit control of a combo box control in a dialog box, form view, or control view object and a CString data member of the dialog box, form view, or control view object.
void AFXAPI DDX_CBStringExact(
CDataExchange* pDX,
int nIDC,
CString& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the combo box control associated with the control property.
value
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_CBStringExact is called, value is set to the current combo box selection. If no item is selected, value is set to a string of zero length.
Note
If the combo box is a drop-down list box, the value exchanged is limited to 255 characters.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_Check
The DDX_Check function manages the transfer of int data between a check box control in a dialog box, form view, or control view object and a int data member of the dialog box, form view, or control view object.
void AFXAPI DDX_Check(
CDataExchange* pDX,
int nIDC,
int& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the check box control associated with the control property.
value
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_Check is called, value is set to the current state of the check box control. For a list of the possible state values, see BM_GETCHECK in the Windows SDK*.*
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_Control
The DDX_Control function subclasses the control, specified by nIDC, of the dialog box, form view, or control view object.
void AFXAPI DDX_Control(
CDataExchange* pDX,
int nIDC,
CWnd& rControl);
Parameters
pDX
A pointer to a CDataExchange object.
nIDC
The resource ID of the control to be subclassed.
rControl
A reference to a member variable of the dialog box, form view, or control view object related to the specified control.
Remarks
The pDX object is supplied by the framework when the DoDataExchange function is called. Therefore, DDX_Control should only be called within your override of DoDataExchange.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_DateTimeCtrl
The DDX_DateTimeCtrl function manages the transfer of date and/or time data between a date and time picker control ( CDateTimeCtrl) in a dialog box or form view object and either a CTime or a COleDateTime data member of the dialog box or form view object.
void AFXAPI DDX_DateTimeCtrl(
CDataExchange* pDX,
int nIDC,
CTime& value);
void AFXAPI DDX_DateTimeCtrl(
CDataExchange* pDX,
int nIDC,
COleDateTime& value);
void AFXAPI DDX_DateTimeCtrl(
CDataExchange* pDX,
int nIDC,
CString& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction. You don't need to delete this object.
nIDC
The resource ID of the date and time picker control associated with the member variable.
value
In the first two versions, a reference to a CTime or COleDateTime member variable, dialog box, form view, or control view object with which data is exchanged. In the third version, a reference to a CString data member control view object.
Remarks
When DDX_DateTimeCtrl is called, value is set to the current state of the date and time picker control, or the control is set to value, depending on the direction of the exchange.
In the third version above, DDX_DateTimeCtrl manages the transfer of CString data between a date time control and a CString data member of the control view object. The string is formatted using the current locale's rules for formatting dates and times.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_IPAddress
The DDX_IPAddress function manages the transfer of data between an IP Address control and a data member of the control view object.
void AFXAPI DDX_IPAddress(
CDataExchange* pDX,
int nIDC,
DWORD& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the IP Address control associated with the control property.
value
A reference to the DWORD containing the four-field value of the IP Address control. The fields are filled or read as follows.
| Field | Bits containing the field value |
|---|---|
| 3 | 0 through 7 |
| 2 | 8 through 15 |
| 1 | 16 through 23 |
| 0 | 24 through 31 |
Use the Win32 IPM_GETADDRESS to read the value, or use IPM_SETADDRESS to fill the value. These messages are described in the Windows SDK.
Remarks
When DDX_IPAddress is called, value is either read from the IP Address control, or value is written to the control, depending on the direction of the exchange.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_LBIndex
The DDX_LBIndex function manages the transfer of int data between a list box control in a dialog box, form view, or control view object and an int data member of the dialog box, form view, or control view object.
void AFXAPI DDX_LBIndex(
CDataExchange* pDX,
int nIDC,
int& index);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the list box control associated with the control property.
index
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_LBIndex is called, index is set to the index of the current list box selection. If no item is selected, index is set to -1.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_LBString
The DDX_LBString function manages the transfer of CString data between a list box control in a dialog box, form view, or control view object and a CString data member of the dialog box, form view, or control view object.
void AFXAPI DDX_LBString(
CDataExchange* pDX,
int nIDC,
CString& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the list box control associated with the control property.
value
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_LBString is called to transfer data to a list box control, the first item in the control whose beginning matches value is selected. (To match the entire item rather than just a prefix, use DDX_LBStringExact.) If there are no matches, no items are selected. The matching is case-insensitive.
When DDX_LBString is called to transfer data from a list box control, value is set to the current list box selection. If no item is selected, value is set to a string of zero length.
Note
If the list box is a drop-down list box, the value exchanged is limited to 255 characters.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_LBStringExact
The DDX_CBStringExact function manages the transfer of CString data between the edit control of a list box control in a dialog box, form view, or control view object and a CString data member of the dialog box, form view, or control view object.
void AFXAPI DDX_LBStringExact(
CDataExchange* pDX,
int nIDC,
CString& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the list box control associated with the control property.
value
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_LBStringExact is called to transfer data to a list box control, the first item in the control that matches value is selected. (To match just a prefix rather than the entire item, use DDX_LBString.) If there are no matches, no items are selected. The matching is case-insensitive.
When DDX_CBStringExact is called to transfer data from a list box control, value is set to the current list box selection. If no item is selected, value is set to a string of zero length.
Note
If the list box is a drop-down list box, the value exchanged is limited to 255 characters.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_MonthCalCtrl
The DDX_MonthCalCtrl function manages the transfer of date data between a month calendar control ( CMonthCalCtrl) in a dialog box, form view, or control view object and either a CTime or a COleDateTime data member of the dialog box, form view, or control view object.
void AFXAPI DDX_MonthCalCtrl(
CDataExchange* pDX,
int nIDC,
CTime& value);
void AFXAPI DDX_MonthCalCtrl(
CDataExchange* pDX,
int nIDC,
COleDateTime& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction. You don't need to delete this object.
nIDC
The resource ID of the month calendar control associated with the member variable.
value
A reference to a CTime or COleDateTime member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
Note
The control manages a date value only. The time fields in the time object are set to reflect the creation time of the control window, or whatever time was set in the control with a call to CMonthCalCtrl::SetCurSel.
When DDX_MonthCalCtrl is called, value is set to the current state of the month calendar control.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_Radio
The DDX_Radio function manages the transfer of int data between a radio control group in a dialog box, form view, or control view object and a int data member of the dialog box, form view, or control view object. The value of the int data member is determined according to which radio button within the group is selected.
void AFXAPI DDX_Radio(
CDataExchange* pDX,
int nIDC,
int& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the first radio control in the group.
value
A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.
Remarks
When DDX_Radio is called, value is set to the current state of the radio control group. The value is set as a 0-based index of the radio control that is currently checked, or -1 if no radio controls are checked.
For example, in case that the first radio button in the group is checked (the button with WS_GROUP style) the value of the int member is 0 and so on.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_Scroll
The DDX_Scroll function manages the transfer of int data between a scroll-bar control in a dialog box, form view, or control view object and an int data member of the dialog box, form view, or control view object.
void AFXAPI DDX_Scroll(
CDataExchange* pDX,
int nIDC,
int& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the scroll-bar control associated with the control property.
value
A reference to a member variable of the dialog box, form view or control view object with which data is exchanged.
Remarks
When DDX_Scroll is called, value is set to the current position of the control's thumb. For more information on the values associated with the current position of the control's thumb, see GetScrollPos in the Windows SDK.
For more information about DDX, see Dialog Data Exchange and Validation.
DDX_Slider
The DDX_Slider function manages the transfer of int data between a slider control in a dialog box or form view and an int data member of the dialog box or form view object.
void AFXAPI DDX_Slider(
CDataExchange* pDX,
int nIDC,
int& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The resource ID of the slider control.
value
A reference to the value to be exchanged. This parameter holds or sets the slider control's current position.
Remarks
When DDX_Slider is called, value is set to the current position of the control's thumb, or the value receives the position, depending on the direction of the exchange.
For more information about DDX, see Dialog Data Exchange and Validation. For information about slider controls, see Using CSliderCtrl.
DDX_Text
The DDX_Text function manages the transfer of int, UINT, long, DWORD, CString, float, or double data between an edit control in a dialog box, form view, or control view and a CString data member of the dialog box, form view, or control view object.
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
BYTE& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
short& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
int& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
UINT& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
long& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
DWORD& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
CString& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
float& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
double& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
COleCurrency& value);
void AFXAPI DDX_Text(
CDataExchange* pDX,
int nIDC,
COleDateTime& value);
Parameters
pDX
A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC
The ID of an edit control in the dialog box, form view, or control view object.
value
A reference to a data member in the dialog box, form view, or control view object. The data type of value depends on which of the overloaded versions of DDX_Text you use.
Remarks
For more information about DDX, see Dialog Data Exchange and Validation.