FileChooser (JavaFX 28)
Description: declaration: module: javafx.graphics, package: javafx.stage, class: FileChooser

# Class FileChooser

java.lang.Object
javafx.stage.FileChooser

public final class FileChooser extends Object
Provides support for standard platform file dialogs. These dialogs have look and feel of the platform UI components which is independent of JavaFX.

On some platforms where file access may be restricted or not part of the user model (for example, on some mobile or embedded devices), opening a file dialog may always result in a no-op (that is, null file(s) being returned).

A `FileChooser` can be used to invoke file open dialogs for selecting single file (`showOpenDialog`), file open dialogs for selecting multiple files (`showOpenMultipleDialog`) and file save dialogs (`showSaveDialog`). The configuration of the displayed dialog is controlled by the values of the `FileChooser` properties set before the corresponding `show*Dialog` method is called. This configuration includes the dialog's title, the initial directory displayed in the dialog and the extension filter(s) for the listed files. For configuration properties which values haven't been set explicitly, the displayed dialog uses their platform default values. A call to a show dialog method is blocked until the user makes a choice or cancels the dialog. The return value specifies the selected file(s) or equals to `null` if the dialog has been canceled.

Example:

    FileChooser fileChooser = new FileChooser();
    fileChooser.setTitle("Open Resource File");
    fileChooser.getExtensionFilters().addAll(
            new ExtensionFilter("Text Files", "*.txt"),
            new ExtensionFilter("Image Files", "*.png", "*.jpg", "*.gif"),
            new ExtensionFilter("Audio Files", "*.wav", "*.mp3", "*.aac"),
            new ExtensionFilter("All Files", "*.*"));
    File selectedFile = fileChooser.showOpenDialog(mainStage);
    if (selectedFile != null) {
       mainStage.display(selectedFile);
    }

Since:
  JavaFX 2.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `FileChooser.ExtensionFilter`
  Defines an extension filter, used for filtering which files can be chosen in a FileDialog based on the file name extensions.

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final ObjectProperty<File>`
  `initialDirectory`
  The initial directory for the displayed file dialog.
  `final ObjectProperty<String>`
  `initialFileName`
  The initial file name for the displayed dialog.
  `final ObjectProperty<FileChooser.ExtensionFilter>`
  `selectedExtensionFilter`
  This property is used to pre-select the extension filter for the next displayed dialog and to read the user-selected extension filter from the dismissed dialog.
  `final StringProperty`
  `title`
  The title of the displayed file dialog.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FileChooser()`
  Creates a `FileChooser`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ObservableList<FileChooser.ExtensionFilter>`
  `getExtensionFilters()`
  Gets the extension filters used in the displayed file dialog.
  `final File`
  `getInitialDirectory()`
  Gets the value of the `initialDirectory` property.
  `final String`
  `getInitialFileName()`
  Gets the value of the `initialFileName` property.
  `final FileChooser.ExtensionFilter`
  `getSelectedExtensionFilter()`
  Gets the value of the `selectedExtensionFilter` property.
  `final String`
  `getTitle()`
  Gets the value of the `title` property.
  `final ObjectProperty<File>`
  `initialDirectoryProperty()`
  The initial directory for the displayed file dialog.
  `final ObjectProperty<String>`
  `initialFileNameProperty()`
  The initial file name for the displayed dialog.
  `final ObjectProperty<FileChooser.ExtensionFilter>`
  `selectedExtensionFilterProperty()`
  This property is used to pre-select the extension filter for the next displayed dialog and to read the user-selected extension filter from the dismissed dialog.
  `final void`
  `setInitialDirectory(File value)`
  Sets the value of the `initialDirectory` property.
  `final void`
  `setInitialFileName(String value)`
  Sets the value of the `initialFileName` property.
  `final void`
  `setSelectedExtensionFilter(FileChooser.ExtensionFilter filter)`
  Sets the value of the `selectedExtensionFilter` property.
  `final void`
  `setTitle(String value)`
  Sets the value of the `title` property.
  `File`
  `showOpenDialog(Window ownerWindow)`
  Shows a new file open dialog.
  `List<File>`
  `showOpenMultipleDialog(Window ownerWindow)`
  Shows a new file open dialog in which multiple files can be selected.
  `File`
  `showSaveDialog(Window ownerWindow)`
  Shows a new file save dialog.
  `final StringProperty`
  `titleProperty()`
  The title of the displayed file dialog.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Property Details

  - ### title

    public final StringProperty titleProperty
    The title of the displayed file dialog.
    See Also:
      - `getTitle()`
      - `setTitle(String)`
      - `titleProperty()`

  - ### initialDirectory

    public final ObjectProperty<File> initialDirectoryProperty
    The initial directory for the displayed file dialog.

    If this path is not set, does not exist, is not a directory, or is not accessible, the dialog will fall back to the platform-default location. The default folder may vary across operating systems.

    See Also:
      - `getInitialDirectory()`
      - `setInitialDirectory(File)`
      - `initialDirectoryProperty()`

  - ### initialFileName

    public final ObjectProperty<String> initialFileNameProperty
    The initial file name for the displayed dialog.

    This property is used mostly in the displayed file save dialogs as the initial file name for the file being saved. If set for a file open dialog it will have any impact on the displayed dialog only if the corresponding platform provides support for such property in its file open dialogs.

    Since:
      JavaFX 2.2.40
    See Also:
      - `getInitialFileName()`
      - `setInitialFileName(String)`
      - `initialFileNameProperty()`

  - ### selectedExtensionFilter

    public final ObjectProperty<FileChooser.ExtensionFilter> selectedExtensionFilterProperty
    This property is used to pre-select the extension filter for the next displayed dialog and to read the user-selected extension filter from the dismissed dialog.

    When the file dialog is shown, the selectedExtensionFilter will be checked. If the value of selectedExtensionFilter is null or is not contained in the list of extension filters, then the first extension filter in the list of extension filters will be selected instead. Otherwise, the specified selectedExtensionFilter will be activated.

    After the dialog is dismissed the value of this property is updated to match the user-selected extension filter from the dialog.

    Since:
      JavaFX 8.0
    See Also:
      - `getSelectedExtensionFilter()`
      - `setSelectedExtensionFilter(FileChooser.ExtensionFilter)`
      - `selectedExtensionFilterProperty()`

- ## Constructor Details

  - ### FileChooser

    public FileChooser()
    Creates a `FileChooser`.

- ## Method Details

  - ### setTitle

    public final void setTitle(String value)
    Sets the value of the `title` property.
    Property description:
      The title of the displayed file dialog.
    Parameters:
      `value` - the value for the `title` property
    See Also:
      - `getTitle()`
      - `titleProperty()`

  - ### getTitle

    public final String getTitle()
    Gets the value of the `title` property.
    Property description:
      The title of the displayed file dialog.
    Returns:
      the value of the `title` property
    See Also:
      - `setTitle(String)`
      - `titleProperty()`

  - ### titleProperty

    public final StringProperty titleProperty()
    The title of the displayed file dialog.
    Returns:
      the `title` property
    See Also:
      - `getTitle()`
      - `setTitle(String)`

  - ### setInitialDirectory

    public final void setInitialDirectory(File value)
    Sets the value of the `initialDirectory` property.
    Property description:
      The initial directory for the displayed file dialog.

      If this path is not set, does not exist, is not a directory, or is not accessible, the dialog will fall back to the platform-default location. The default folder may vary across operating systems.

    Parameters:
      `value` - the value for the `initialDirectory` property
    See Also:
      - `getInitialDirectory()`
      - `initialDirectoryProperty()`

  - ### getInitialDirectory

    public final File getInitialDirectory()
    Gets the value of the `initialDirectory` property.
    Property description:
      The initial directory for the displayed file dialog.

      If this path is not set, does not exist, is not a directory, or is not accessible, the dialog will fall back to the platform-default location. The default folder may vary across operating systems.

    Returns:
      the value of the `initialDirectory` property
    See Also:
      - `setInitialDirectory(File)`
      - `initialDirectoryProperty()`

  - ### initialDirectoryProperty

    public final ObjectProperty<File> initialDirectoryProperty()
    The initial directory for the displayed file dialog.

    If this path is not set, does not exist, is not a directory, or is not accessible, the dialog will fall back to the platform-default location. The default folder may vary across operating systems.

    Returns:
      the `initialDirectory` property
    See Also:
      - `getInitialDirectory()`
      - `setInitialDirectory(File)`

  - ### setInitialFileName

    public final void setInitialFileName(String value)
    Sets the value of the `initialFileName` property.
    Property description:
      The initial file name for the displayed dialog.

      This property is used mostly in the displayed file save dialogs as the initial file name for the file being saved. If set for a file open dialog it will have any impact on the displayed dialog only if the corresponding platform provides support for such property in its file open dialogs.

    Parameters:
      `value` - the value for the `initialFileName` property
    Since:
      JavaFX 2.2.40
    See Also:
      - `getInitialFileName()`
      - `initialFileNameProperty()`

  - ### getInitialFileName

    public final String getInitialFileName()
    Gets the value of the `initialFileName` property.
    Property description:
      The initial file name for the displayed dialog.

      This property is used mostly in the displayed file save dialogs as the initial file name for the file being saved. If set for a file open dialog it will have any impact on the displayed dialog only if the corresponding platform provides support for such property in its file open dialogs.

    Returns:
      the value of the `initialFileName` property
    Since:
      JavaFX 2.2.40
    See Also:
      - `setInitialFileName(String)`
      - `initialFileNameProperty()`

  - ### initialFileNameProperty

    public final ObjectProperty<String> initialFileNameProperty()
    The initial file name for the displayed dialog.

    This property is used mostly in the displayed file save dialogs as the initial file name for the file being saved. If set for a file open dialog it will have any impact on the displayed dialog only if the corresponding platform provides support for such property in its file open dialogs.

    Returns:
      the `initialFileName` property
    Since:
      JavaFX 2.2.40
    See Also:
      - `getInitialFileName()`
      - `setInitialFileName(String)`

  - ### getExtensionFilters

    public ObservableList<FileChooser.ExtensionFilter> getExtensionFilters()
    Gets the extension filters used in the displayed file dialog. Only one extension filter from the list is active at any time in the displayed dialog and only files which correspond to this extension filter are shown. The first extension filter from the list is activated when the dialog is invoked. Then the user can switch the active extension filter to any other extension filter from the list and in this way control the set of displayed files.
    Returns:
      An observable list of the extension filters used in this dialog

  - ### selectedExtensionFilterProperty

    public final ObjectProperty<FileChooser.ExtensionFilter> selectedExtensionFilterProperty()
    This property is used to pre-select the extension filter for the next displayed dialog and to read the user-selected extension filter from the dismissed dialog.

    When the file dialog is shown, the selectedExtensionFilter will be checked. If the value of selectedExtensionFilter is null or is not contained in the list of extension filters, then the first extension filter in the list of extension filters will be selected instead. Otherwise, the specified selectedExtensionFilter will be activated.

    After the dialog is dismissed the value of this property is updated to match the user-selected extension filter from the dialog.

    Returns:
      the `selectedExtensionFilter` property
    Since:
      JavaFX 8.0
    See Also:
      - `getSelectedExtensionFilter()`
      - `setSelectedExtensionFilter(FileChooser.ExtensionFilter)`

  - ### setSelectedExtensionFilter

    public final void setSelectedExtensionFilter(FileChooser.ExtensionFilter filter)
    Sets the value of the `selectedExtensionFilter` property.
    Property description:
      This property is used to pre-select the extension filter for the next displayed dialog and to read the user-selected extension filter from the dismissed dialog.

      When the file dialog is shown, the selectedExtensionFilter will be checked. If the value of selectedExtensionFilter is null or is not contained in the list of extension filters, then the first extension filter in the list of extension filters will be selected instead. Otherwise, the specified selectedExtensionFilter will be activated.

      After the dialog is dismissed the value of this property is updated to match the user-selected extension filter from the dialog.

    Parameters:
      `filter` - the value for the `selectedExtensionFilter` property
    Since:
      JavaFX 8.0
    See Also:
      - `getSelectedExtensionFilter()`
      - `selectedExtensionFilterProperty()`

  - ### getSelectedExtensionFilter

    public final FileChooser.ExtensionFilter getSelectedExtensionFilter()
    Gets the value of the `selectedExtensionFilter` property.
    Property description:
      This property is used to pre-select the extension filter for the next displayed dialog and to read the user-selected extension filter from the dismissed dialog.

      When the file dialog is shown, the selectedExtensionFilter will be checked. If the value of selectedExtensionFilter is null or is not contained in the list of extension filters, then the first extension filter in the list of extension filters will be selected instead. Otherwise, the specified selectedExtensionFilter will be activated.

      After the dialog is dismissed the value of this property is updated to match the user-selected extension filter from the dialog.

    Returns:
      the value of the `selectedExtensionFilter` property
    Since:
      JavaFX 8.0
    See Also:
      - `setSelectedExtensionFilter(FileChooser.ExtensionFilter)`
      - `selectedExtensionFilterProperty()`

  - ### showOpenDialog

    public File showOpenDialog(Window ownerWindow)
    Shows a new file open dialog. The method doesn't return until the displayed open dialog is dismissed. The return value specifies the file chosen by the user or `null` if no selection has been made. If the owner window for the file dialog is set, input to all windows in the dialog's owner chain is blocked while the file dialog is being shown.
    Parameters:
      `ownerWindow` - the owner window of the displayed file dialog
    Returns:
      the selected file or `null` if no file has been selected

  - ### showOpenMultipleDialog

    public List<File> showOpenMultipleDialog(Window ownerWindow)
    Shows a new file open dialog in which multiple files can be selected. The method doesn't return until the displayed open dialog is dismissed. The return value specifies the files chosen by the user or `null` if no selection has been made. If the owner window for the file dialog is set, input to all windows in the dialog's owner chain is blocked while the file dialog is being shown.

    The returned list is unmodifiable and will throw `UnsupportedOperationException` on each modification attempt.

    Parameters:
      `ownerWindow` - the owner window of the displayed file dialog
    Returns:
      the selected files or `null` if no file has been selected

  - ### showSaveDialog

    public File showSaveDialog(Window ownerWindow)
    Shows a new file save dialog. The method doesn't return until the displayed file save dialog is dismissed. The return value specifies the file chosen by the user or `null` if no selection has been made. If the owner window for the file dialog is set, input to all windows in the dialog's owner chain is blocked while the file dialog is being shown.
    Parameters:
      `ownerWindow` - the owner window of the displayed file dialog
    Returns:
      the selected file or `null` if no file has been selected