DlgDirSelectExA function (winuser.h)

Article
02/09/2023

Retrieves the current selection from a single-selection list box. It assumes that the list box has been filled by the DlgDirList function and that the selection is a drive letter, filename, or directory name.

Syntax

BOOL DlgDirSelectExA(
  [in]  HWND  hwndDlg,
  [out] LPSTR lpString,
  [in]  int   chCount,
  [in]  int   idListBox
);

Parameters

[in] hwndDlg

Type: HWND

A handle to the dialog box that contains the list box.

[out] lpString

Type: LPTSTR

A pointer to a buffer that receives the selected path.

[in] chCount

Type: int

The length, in TCHARs, of the buffer pointed to by lpString.

[in] idListBox

Type: int

The identifier of a list box in the dialog box.

Return value

Type: BOOL

If the current selection is a directory name, the return value is nonzero.

If the current selection is not a directory name, the return value is zero. To get extended error information, call GetLastError.

Remarks

The DlgDirSelectEx function copies the selection to the buffer pointed to by the lpString parameter. If the current selection is a directory name or drive letter, DlgDirSelectEx removes the enclosing square brackets (and hyphens, for drive letters), so that the name or letter is ready to be inserted into a new path. If there is no selection, lpString does not change.

If the string is as long or longer than the buffer, the buffer will contain the truncated string with a terminating null character.

DlgDirSelectEx sends LB_GETCURSEL and LB_GETTEXT messages to the list box. The function does not allow more than one filename to be returned from a list box. The list box must not be a multiple-selection list box. If it is, this function does not return a zero value and lpString remains unchanged.

Windows 95 or later: DlgDirSelectExW is supported by the Microsoft Layer for Unicode. To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows Me/98/95 Systems.

Examples

For an example, see Creating a Directory Listing in a Single-selection List Box.

Note

The winuser.h header defines DlgDirSelectEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll