---
title: "fileChooser"
canonical: "https://help.vicon.com/space/ShogunPost121/1253737206/fileChooser"
format: markdown
---
# Description

Prompts the user to select a file on the file system in the system **File Browser**.

The **File Browser** is a dialog box designed for easy file/file name selection. By default, the **File Browser** does not filter on file types, however, filters can be provided using the `-filters` flag. The filters string is contains a sequence of filter descriptions, followed by the actual filter (eg, .c3d). Descriptions and extensions are separated using the | character, as are subsequent descriptions and extensions. For example, to filter on .c3d and .csm files, a filters string will look like this:

```plaintext
"Binary Motion File (.c3d)|.c3d|Character Studio (.csm)|.csm"
```

An All Files `(.*)` will automatically be appended to any filter string specified.

If the user hits the **Cancel** button (i.e. chooses no directory) and `-failOnCancel` is specified, the command will fail, causing the calling script to abort.

If `-failOnCancel` is not specified, the command will return an empty string (`""`).

Because the file must return multiple file paths if the `-multi` flag is specified, the command must return an array of strings. If `-multi` is not specified, a one element string array will be returned.

Note that in HSL, directories in file paths are separated by forward-slashes ( / ), rather than back-slashes ( \ ).

## Functional area

User Window

# Command syntax

## Syntax

> Macro (scroll-tablelayout)

|  |
| --- |
| `fileChooser [-owner integer] [-ext string] [-file string] [-dir string] [-filters string] [-multi] [-createPrompt] [-mustExist] [-failOnCancel]` |

### Arguments

None 

> Macro (scroll-pagebreak)

### Flags

> Macro (scroll-tablelayout)

| Name | Flag arguments | Argument type | Exclusive to | Comments |
| --- | --- | --- | --- | --- |
| `owner` | 1 | integer | — | Specifies the window ID of a user window to be the "owner" of the **File Browser**. Essentially centers the Browser to the User Window. |
| `ext` | 1 | string | — | The default file extension (e.g. *c3d*) to append to the selected filename, if it does not have one. The default is no action. |
| `file` | 1 | string | — | — |
| `dir` | 1 | string | — | Specifies the initial directory of the **File Browser** when it is displayed. The default is the current directory. |
| `filters` | 1 | string | — | Specifies the file type filters. By default, the **File Browser** displays all files. Files can be filtered down by extension, or even by `fileClose` |
| `multi` | 0 | — | — | — |
| `createPrompt` | 0 | — | — | — |
| `must exist` | 0 | — | — | — |
| `failOnCancel` | 0 | — | — | — |
| `mustExist` | 0 | — | — | — |

## Return value

string array 

> Macro (scroll-pagebreak)

## Examples

```plaintext
// Prompt the user to select file.
string  $files[]; 
string  $initialPath = "C:/";
string  $filter = "Binary Motion File (*.c3d)|*.c3d|Character Studio (*.csm)|*.csm";
 
// Specify the initial directory, the filters, and that the file they
// select must exist.
$files = `fileChooser -dir $initialPath -filters $filter -mustExist`;
print $files;
```

# Additional information

## Related commands

- [dirChooser](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost121/pages/1253736965)