s = CS.Path.getDirectoryListing(path := ...
ʃ, recursive := ...ʅ
ʃ, filter := ...ʅ
ʃ, filterDirectories := ...ʅ
ʃ, type := ...ʅ
ʃ, detailed := ...ʅ)
Argument | Description | Types / Required |
path | The path of a directory. | string
required |
recursive | If true, the listing will include paths in path's subdirectories.
The default value is false. | boolean
not required |
filter | A wildcard used to filter the files and, if applicable, the directories. | string
not required |
filterDirectories | If true, the filter will also apply to directories.
The default value is false. | boolean
not required |
type | If defined, the paths included can be filtered using the value "file" or "directory". | string
not required |
detailed | If true, the returned paths will include details in the format of Path.getPathInfo.
The default value is false. | boolean
not required |
The
Path.getDirectoryListing action returns information about the paths in the directory specified as
path. Generally
path is a directory, but it can also be one of the following special values, specified with the
"|" prefix:
- The Android root directory, specified as "|Android".
- An Android Media Store directory, specified as one of the following: "|Media.Audio", "|Media.Images", or "|Media.Video". Note that files in these "directories" can actually reside in multiple directories.
By default, only files and directories located in the specified directory are returned. The recursive argument can be used to recursively add paths, getting information about the specified directory as well as any subdirectories.
Information about both files and directories is returned, but this can be modified by specifying a type. Hidden and system files are never included. Directory paths are returned without a trailing slash.
When
detailed is
true, the path information is returned in the format as returned by
Path.getPathInfo. If
false, the path information is returned as a string containing the fully evaluated path.
You can specify a wildcard
filter that restricts the paths returned by the action. By default, the wildcard filter applies only to the names of files, but by setting
filterDirectories to
true, the filter will also apply to the names of directories. The filter does not apply to a path's directory but only its name component. For example,
"*.csdb" would include only the paths of
CSPro DB data sources. You can specify multiple wildcard filters by separating each filter with a semicolon. The filter
"*.jpg;*.jpeg;*.bmp" would include both JPEG and BMP files. In addition to standard wildcard filters, you can use a predefined wildcard expression, specified with the
"|" prefix:
- "|FileType.Audio": Files that the Audio object can read and write.
- "|FileType.Geometry": Files that the Geometry object can read and write.
- "|FileType.Image": Files that the Image object can read and write.
A directory listing can also be retrieved using the
dirlist function.
The action returns an object containing the properties:
Property | Value |
"path" | A string containing the fully evaluated directory path. |
"parent" | A string containing the path's fully evaluated parent directory (if applicable). |
"paths" | An array containing the information about paths in the directory, returned as objects or strings (depending on detailed). |
The action throws an exception if any of its arguments are not specified in a valid form or if the directory does not exist.
// get a list of the HTML dialogs included with CSPro
const htmlDialogs = CS.Path.getDirectoryListing({
path: CS.Path.getSpecialPaths().html + "/dialogs",
filter: "*.html"
});
Possible result:
{
"path": "C:\\Program Files (x86)\\CSPro 8.0\\html\\dialogs",
"parent": "C:\\Program Files (x86)\\CSPro 8.0\\html",
"paths": [
"C:\\Program Files (x86)\\CSPro 8.0\\html\\dialogs\\choice.html",
"C:\\Program Files (x86)\\CSPro 8.0\\html\\dialogs\\text-input.html"
]
}
// get a detailed list of the HTML dialogs included with CSPro, starting with 'c'
const htmlDialogs = CS.Path.getDirectoryListing({
path: CS.Path.getSpecialPaths().html + "/dialogs",
filter: "c*.html",
detailed: true
});
Possible result:
{
"path": "C:\\Program Files (x86)\\CSPro 8.0\\html\\dialogs",
"parent": "C:\\Program Files (x86)\\CSPro 8.0\\html",
"paths": [
{
"path": "C:/Program Files (x86)/CSPro 8.0/html/dialogs/choice.html",
"name": "choice.html",
"extension": "html",
"contentType": "text/html",
"exists": true,
"type": "file",
"modifiedTime": "2024-01-01T06:24:00Z",
"size": 10583
}
]
}