CWnd::DlgDirList

Fills a list box with a file or directory listing.

int DlgDirList(
   LPTSTR lpPathSpec,
   int nIDListBox,
   int nIDStaticPath,
   UINT nFileType 
);

Parameters

  • lpPathSpec
    Points to a null-terminated string that contains the path or filename. DlgDirList modifies this string, which should be long enough to contain the modifications. For more information, see the following "Remarks" section.

  • nIDListBox
    Specifies the identifier of a list box. If nIDListBox is 0, DlgDirList assumes that no list box exists and does not attempt to fill one.

  • nIDStaticPath
    Specifies the identifier of the static-text control used to display the current drive and directory. If nIDStaticPath is 0, DlgDirList assumes that no such text control is present.

  • nFileType
    Specifies the attributes of the files to be displayed. It can be any combination of the following values:

    • DDL_READWRITE   Read-write data files with no additional attributes.

    • DDL_READONLY   Read-only files.

    • DDL_HIDDEN   Hidden files.

    • DDL_SYSTEM   System files.

    • DDL_DIRECTORY   Directories.

    • DDL_ARCHIVE   Archives.

    • DDL_POSTMSGS   LB_DIR flag. If the LB_DIR flag is set, Windows places the messages generated by DlgDirList in the application's queue; otherwise, they are sent directly to the dialog-box procedure.

    • DDL_DRIVES   Drives. If the DDL_DRIVES flag is set, the DDL_EXCLUSIVE flag is set automatically. Therefore, to create a directory listing that includes drives and files, you must call DlgDirList twice: once with the DDL_DRIVES flag set and once with the flags for the rest of the list.

    • DDL_EXCLUSIVE   Exclusive bit. If the exclusive bit is set, only files of the specified type are listed; otherwise normal files and files of the specified type are listed.

Return Value

Nonzero if the function is successful; otherwise 0.

Remarks

DlgDirList sends LB_RESETCONTENT and LB_DIR messages to the list box. It fills the list box specified by nIDListBox with the names of all files that match the path given by lpPathSpec.

The lpPathSpec parameter has the following form:

[drive:] [ [\u]directory[\idirectory]...\u] [filename]

In this example, drive is a drive letter, directory is a valid directory name, and filename is a valid filename that must contain at least one wildcard. The wildcards are a question mark (?), which means match any character, and an asterisk (*), meaning match any number of characters.

If you specify a 0-length string for lpPathSpec, or if you specify only a directory name but do not include any file specification, the string will be changed to "*.*".

If lpPathSpec includes a drive and/or directory name, the current drive and directory are changed to the designated drive and directory before the list box is filled. The text control identified by nIDStaticPath is also updated with the new drive and/or directory name.

After the list box is filled, lpPathSpec is updated by removing the drive and/or directory portion of the path.

Example

// If pDialog points to a CDialog object with a list box
// with the identifier IDC_DIRLIST, this call will populate
// the box with only the non-hidden subdirectories in the root
// directory of the C:\ drive.
TCHAR path[MAX_PATH];
_tcscpy_s(path, MAX_PATH, _T("C:\\"));

pDialog->DlgDirList(path, IDC_DIRLIST, 0, DDL_EXCLUSIVE | DDL_DIRECTORY);

Requirements

Header: afxwin.h

See Also

Concepts

CWnd Class

CWnd Members

Hierarchy Chart

CWnd::DlgDirListComboBox

DlgDirList