Applies to: desktop apps only
Retrieves a handle to a control in the specified dialog box.
Syntax
HWND WINAPI GetDlgItem( __in_opt HWND hDlg, __in int nIDDlgItem );
Parameters
- hDlg [in, optional]
-
Type: HWND
A handle to the dialog box that contains the control.
- nIDDlgItem [in]
-
Type: int
The identifier of the control to be retrieved.
Return value
Type: HWND
If the function succeeds, the return value is the window handle of the specified control.
If the function fails, the return value is NULL, indicating an invalid dialog box handle or a nonexistent control. To get extended error information, call GetLastError.
Remarks
You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the hDlg parameter specifies a parent window and the child window has a unique identifier (as specified by the hMenu parameter in the CreateWindow or CreateWindowEx function that created the child window), GetDlgItem returns a valid handle to the child window.
Examples
For an example, see Initializing a Dialog Box.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- Reference
- CreateWindow
- CreateWindowEx
- GetDlgItemInt
- GetDlgItemText
- Conceptual
- Dialog Boxes
Send comments about this topic to Microsoft
Build date: 2/10/2012
Although the spec does say that this function can return NULL, in practice it is extremely unlikely that this would happen for any reason other than you passing an invalid item ID - in which case you want it to crash - so checking for NULL return value with every call isn't necessary. For trapping mistakes when debugging (source level) you could use assert() from <assert.h> or ASSERT() from MFC/ATL as follows:
#include <assert.h>
...
HWND hItemWnd = GetDlgItem(hParentWnd, IDC_CONTROLID);
assert(hItemWnd != 0);
assert(IsWindow(hItemWnd) != 0);
...
Also, don't know if mentioned already but don't forget: although the name is GetDlgItem() it works on any top-level window, not just dialogs.
Without inside knowledge it's impossible to say how Windows stores and locates dialog IDs. One hopes they would use a balanced binary tree or at least sorted array or list... It's unlikely that they would re-use functions that they export for USER programs to search.
However, it is sensible to call GetDlgItem() once and re-use the handle rather than repeatedly calling GetDlgItem(), although for reasons more to do with readability than performance; it also makes it easier to 'see' the window handle value when source-level debugging. And unless you have an extremely control-dense window, even a linear search costs virtually nothing these days, so you are unlikely to notice any difference in execution speed if you do repeatedly call GetDlgItem().
for (hDlg=GetWindow(hDlg,GW_CHILD); hDlg; hDlg=GetWindow(hDlg,GW_HWNDNEXT))
if (GetDlgCtrlId(hDlg)==nIDDlgItem) return hDlg;
return 0;
therefore, it's a good idea to cache the window handle for larger dialog boxes or frequent use.
The opposite function is
int GetDlgCtrlId(HWND hDlg)which returns the child ID for a window handle.
[DllImport("user32.dll", CharSet=CharSet.Auto, ExactSpelling=true)]
public static extern IntPtr GetDlgItem(HandleRef hWnd, int nIDDlgItem);