CWnd::DlgDirList

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

Return Value

Nonzero if the function is successful; otherwise 0.

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.

Remarks

Fills a list box with a file or directory listing. 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.

pDialog->DlgDirList(_T("C:\\"), IDC_DIRLIST, 0,
   DDL_EXCLUSIVE | DDL_DIRECTORY);

CWnd Overview | Class Members | Hierarchy Chart