Applies to: desktop apps only
Retrieves a handle to the first control that has the WS_TABSTOP style that precedes (or follows) the specified control.
Syntax
HWND WINAPI GetNextDlgTabItem( __in HWND hDlg, __in_opt HWND hCtl, __in BOOL bPrevious );
Parameters
- hDlg [in]
-
Type: HWND
A handle to the dialog box to be searched.
- hCtl [in, optional]
-
Type: HWND
A handle to the control to be used as the starting point for the search. If this parameter is NULL, the function fails.
- bPrevious [in]
-
Type: BOOL
Indicates how the function is to search the dialog box. If this parameter is TRUE, the function searches for the previous control in the dialog box. If this parameter is FALSE, the function searches for the next control in the dialog box.
Return value
Type: HWND
If the function succeeds, the return value is the window handle of the previous (or next) control that has the WS_TABSTOP style set.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
The GetNextDlgTabItem function searches controls in the order (or reverse order) they were created in the dialog box template. The function returns the first control it locates that is visible, not disabled, and has the WS_TABSTOP style. If no such control exists, the function returns hCtl.
If the search for the next control with the WS_TABSTOP style encounters a window with the WS_EX_CONTROLPARENT style, the system recursively searches the window's children.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- Reference
- GetDlgItem
- GetNextDlgGroupItem
- Conceptual
- Dialog Boxes
Send comments about this topic to Microsoft
Build date: 2/10/2012
The docmentation states for the second parameter:
"If this is NULL, the function fails."
This is not true. The function does not fail, in fact it is quite useful to call this API with that parameter set to NULL as it gives you a way to find the "first" or "last" control on a dialog with the WS_TABSTOP style.
Also, note that the Windows CE documentation for the GetNextDlgTabItem() API has more accurate info for this parameter where it states:
"If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search."
<< If this is NULL, the function fails. >>
That's not true. The function does not fail. In fact it is quite useful to call this function wth the second parameter set to NULL if for example you wanted the search to begin with the very first control in the dialog box. Microsoft's own Property Sheet code uses this technique to determine which control to set the focus to on a property page after a user presses the Apply button. It needs to set focus to a control other than the Apply button because the Apply button gets disabled after it is clicked and since Microsoft has no idea what kind of controls are on an application's property page it sets the second parameter to NULL to ask the GetNextDlgTabItem() API to go and get the first control which has the WS_TABSTOP style. (On a side note, the Property Sheet code then goes on to make sure the control is visible and enabled before setting focus to it, but that's another topic altogether).
Anyway, interestingly enough the documentation for this API in the Windows CE documentation happens to be different and accurate! ;-)
<< If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search. >>
Cheers,
Alan