APIdia Launch Partner
Top Description Fields Constructors Methods
java.awt

public Class FileDialog

extends Dialog
Class Inheritance
Imports
java.awt.peer.FileDialogPeer, java.io.File, .FilenameFilter, .IOException, .ObjectInputStream, .Serial, java.lang.annotation.Native, sun.awt.AWTAccessor
The FileDialog class displays a dialog window from which the user can select a file.

Since it is a modal dialog, when the application calls its show method to display the dialog, it blocks the rest of the application until the user has chosen a file. This means that Dialog#setModalityType(ModalityType) may be ignored.

Authors
Sami Shaio, Arthur van Hoff
Since
1.0
See Also
Window#show

Field Summary

Modifier and TypeField and Description
private static final String
base

Hides java.awt.Dialog.base.

pack-priv String
dir

The string specifying the directory to display in the file dialog.

pack-priv String
file

The string specifying the initial value of the filename text field in the file dialog.

private File[]
files

Contains the File instances for all the files that the user selects.

pack-priv FilenameFilter
filter

The filter used as the file dialog's filename filter.

public static final int
LOAD

This constant value indicates that the purpose of the file dialog window is to locate a file from which to read.

pack-priv int
mode

There are two FileDialog modes: LOAD and SAVE.

private boolean
multipleMode

Represents whether the file dialog allows the multiple file selection.

private static int
nameCounter

Hides java.awt.Dialog.nameCounter.

public static final int
SAVE

This constant value indicates that the purpose of the file dialog window is to locate a file to which to write.

private static final long
serialVersionUID

Hides java.awt.Dialog.serialVersionUID.

Use serialVersionUID from JDK 1.1 for interoperability.
Inherited from java.awt.Dialog:
blockedWindowsDEFAULT_MODALITY_TYPEisInDisposeisInHidemodalmodalDialogsmodalityTyperesizabletitleundecorated

Constructor Summary

AccessConstructor and Description
public
FileDialog(Frame
the owner of the dialog
parent)

Creates a file dialog for loading a file.

public
FileDialog(Frame
the owner of the dialog
parent, String
the title of the dialog
title)

Creates a file dialog window with the specified title for loading a file.

public
FileDialog(Frame
the owner of the dialog
parent, String
the title of the dialog
title, int
the mode of the dialog; either FileDialog.LOAD or FileDialog.SAVE
mode)

Creates a file dialog window with the specified title for loading or saving a file.

public
FileDialog(Dialog
the owner of the dialog
parent)

Creates a file dialog for loading a file.

public
FileDialog(Dialog
the owner of the dialog
parent, String
the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown
title)

Creates a file dialog window with the specified title for loading a file.

public
FileDialog(Dialog
the owner of the dialog
parent, String
the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown
title, int
the mode of the dialog; either FileDialog.LOAD or FileDialog.SAVE
mode)

Creates a file dialog window with the specified title for loading or saving a file.

Method Summary

Modifier and TypeMethod and Description
public void
addNotify()

Overrides java.awt.Dialog.addNotify.

Creates the file dialog's peer.

pack-priv String
constructComponentName()

Overrides java.awt.Dialog.constructComponentName.

Constructs a name for this component.

public String

Returns:

the (potentially null or invalid) directory of this FileDialog
getDirectory()

Gets the directory of this file dialog.

public String

Returns:

the currently selected file of this file dialog window, or null if none is selected
getFile()

Gets the selected file of this file dialog.

public FilenameFilter

Returns:

this file dialog's filename filter
getFilenameFilter()

Determines this file dialog's filename filter.

public File[]

Returns:

files that the user selects or an empty array if the user cancels the file dialog.
getFiles()

Returns files that the user selects.

public int

Returns:

the mode of this file dialog window, either FileDialog.LOAD or FileDialog.SAVE
getMode()

Indicates whether this file dialog box is for loading from a file or for saving to a file.

public boolean

Returns:

true if the file dialog allows the multiple file selection; false otherwise.
isMultipleMode()

Returns whether the file dialog allows the multiple file selection.

protected String

Returns:

the parameter string of this file dialog window
paramString()

Overrides java.awt.Dialog.paramString.

Returns a string representing the state of this FileDialog window.

pack-priv boolean
postsOldMouseEvents()

Overrides java.awt.Container.postsOldMouseEvents.

private void
readObject(ObjectInputStream
the ObjectInputStream to read
s)

Hides java.awt.Dialog.readObject.

Reads the ObjectInputStream and performs a backwards compatibility check by converting either a dir or a file equal to an empty string to null.

public void
setDirectory(String
the specified directory
dir)

Sets the directory of this file dialog window to be the specified directory.

public void
setFile(String
the file being set
file)

Sets the selected file for this file dialog window to be the specified file.

public synchronized void
setFilenameFilter(FilenameFilter
the specified filter
filter)

Sets the filename filter for this file dialog window to the specified filter.

private void
setFiles(File[]
the array that contains the short names of all the files that the user selects.
files)

Stores the names of all the files that the user selects.

public void
setMode(int
the mode for this file dialog, either FileDialog.LOAD or FileDialog.SAVE
mode)

Sets the mode of the file dialog.

public void
setMultipleMode(boolean
if true, multiple file selection is enabled; false - disabled.
enable)

Enables or disables multiple file selection for the file dialog.

public void
setTitle(String title)

Overrides java.awt.Dialog.setTitle.

Sets the title of the Dialog.

Inherited from java.awt.Dialog:
blockWindowblockWindowscheckShouldBeBlockeddoDisposegetAccessibleContextgetModalityTypegetTitlehideisModalisModal_NoClientCodeisResizableisUndecoratedmodalHidemodalityPoppedmodalityPushedmodalShowsetBackgroundsetModalsetModalityTypesetOpacitysetResizablesetShapesetUndecoratedsetVisibleshouldBlockshowtoBackunblockWindow

Field Detail

baseback to summary
private static final String base

Hides java.awt.Dialog.base.

dirback to summary
pack-priv String dir

The string specifying the directory to display in the file dialog. This variable may be null.

See Also
getDirectory, setDirectory
fileback to summary
pack-priv String file

The string specifying the initial value of the filename text field in the file dialog. This variable may be null.

See Also
getFile, setFile
filesback to summary
private File[] files

Contains the File instances for all the files that the user selects.

Since
1.7
See Also
getFiles
filterback to summary
pack-priv FilenameFilter filter

The filter used as the file dialog's filename filter. The file dialog will only be displaying files whose names are accepted by this filter. This variable may be null.

Annotations
@SuppressWarnings:serial
See Also
getFilenameFilter, setFilenameFilter, FilenameFilter
LOADback to summary
public static final int LOAD

This constant value indicates that the purpose of the file dialog window is to locate a file from which to read.

Annotations
@Native
modeback to summary
pack-priv int mode

There are two FileDialog modes: LOAD and SAVE. This integer will represent one or the other. If the mode is not specified it will default to LOAD.

See Also
getMode, setMode, java.awt.FileDialog#LOAD, java.awt.FileDialog#SAVE
multipleModeback to summary
private boolean multipleMode

Represents whether the file dialog allows the multiple file selection.

Since
1.7
See Also
setMultipleMode, isMultipleMode
nameCounterback to summary
private static int nameCounter

Hides java.awt.Dialog.nameCounter.

SAVEback to summary
public static final int SAVE

This constant value indicates that the purpose of the file dialog window is to locate a file to which to write.

Annotations
@Native
serialVersionUIDback to summary
private static final long serialVersionUID

Hides java.awt.Dialog.serialVersionUID.

Use serialVersionUID from JDK 1.1 for interoperability.

Annotations
@Serial

Constructor Detail

FileDialogback to summary
public FileDialog(Frame parent)

Creates a file dialog for loading a file. The title of the file dialog is initially empty. This is a convenience method for FileDialog(parent, "", LOAD).

Note

Some platforms may not support showing the user-specified title in a file dialog. In this situation, either no title will be displayed in the file dialog's title bar or, on some systems, the file dialog's title bar will not be displayed.

Parameters
parent:Frame

the owner of the dialog

Since
1.1
FileDialogback to summary
public FileDialog(Frame parent, String title)

Creates a file dialog window with the specified title for loading a file. The files shown are those in the current directory. This is a convenience method for FileDialog(parent, title, LOAD).

Note

Some platforms may not support showing the user-specified title in a file dialog. In this situation, either no title will be displayed in the file dialog's title bar or, on some systems, the file dialog's title bar will not be displayed.

Parameters
parent:Frame

the owner of the dialog

title:String

the title of the dialog

FileDialogback to summary
public FileDialog(Frame parent, String title, int mode)

Creates a file dialog window with the specified title for loading or saving a file.

If the value of mode is LOAD, then the file dialog is finding a file to read, and the files shown are those in the current directory. If the value of mode is SAVE, the file dialog is finding a place to write a file.

Note

Some platforms may not support showing the user-specified title in a file dialog. In this situation, either no title will be displayed in the file dialog's title bar or, on some systems, the file dialog's title bar will not be displayed.

Parameters
parent:Frame

the owner of the dialog

title:String

the title of the dialog

mode:int

the mode of the dialog; either FileDialog.LOAD or FileDialog.SAVE

Exceptions
IllegalArgumentException:
if an illegal file dialog mode is supplied
See Also
java.awt.FileDialog#LOAD, java.awt.FileDialog#SAVE
FileDialogback to summary
public FileDialog(Dialog parent)

Creates a file dialog for loading a file. The title of the file dialog is initially empty. This is a convenience method for FileDialog(parent, "", LOAD).

Note

Some platforms may not support showing the user-specified title in a file dialog. In this situation, either no title will be displayed in the file dialog's title bar or, on some systems, the file dialog's title bar will not be displayed.

Parameters
parent:Dialog

the owner of the dialog

Exceptions
IllegalArgumentException:
  • if the parent's GraphicsConfiguration is not from a screen device;
  • if parent is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
Since
1.5
See Also
java.awt.GraphicsEnvironment#isHeadless
FileDialogback to summary
public FileDialog(Dialog parent, String title)

Creates a file dialog window with the specified title for loading a file. The files shown are those in the current directory. This is a convenience method for FileDialog(parent, title, LOAD).

Note

Some platforms may not support showing the user-specified title in a file dialog. In this situation, either no title will be displayed in the file dialog's title bar or, on some systems, the file dialog's title bar will not be displayed.

Parameters
parent:Dialog

the owner of the dialog

title:String

the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown

Exceptions
IllegalArgumentException:
  • if the parent's GraphicsConfiguration is not from a screen device;
  • if parent is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
Since
1.5
See Also
java.awt.GraphicsEnvironment#isHeadless
FileDialogback to summary
public FileDialog(Dialog parent, String title, int mode)

Creates a file dialog window with the specified title for loading or saving a file.

If the value of mode is LOAD, then the file dialog is finding a file to read, and the files shown are those in the current directory. If the value of mode is SAVE, the file dialog is finding a place to write a file.

Note

Some platforms may not support showing the user-specified title in a file dialog. In this situation, either no title will be displayed in the file dialog's title bar or, on some systems, the file dialog's title bar will not be displayed.

Parameters
parent:Dialog

the owner of the dialog

title:String

the title of the dialog; a null value will be accepted without causing a NullPointerException to be thrown

mode:int

the mode of the dialog; either FileDialog.LOAD or FileDialog.SAVE

Exceptions
IllegalArgumentException:
  • if an illegal file dialog mode is supplied;
  • if the parent's GraphicsConfiguration is not from a screen device;
  • if parent is null; this exception is always thrown when GraphicsEnvironment.isHeadless returns true
Since
1.5
See Also
java.awt.GraphicsEnvironment#isHeadless, java.awt.FileDialog#LOAD, java.awt.FileDialog#SAVE

Method Detail

addNotifyback to summary
public void addNotify()

Overrides java.awt.Dialog.addNotify.

Creates the file dialog's peer. The peer allows us to change the look of the file dialog without changing its functionality.

constructComponentNameback to summary
pack-priv String constructComponentName()

Overrides java.awt.Dialog.constructComponentName.

Constructs a name for this component. Called by getName() when the name is null.

getDirectoryback to summary
public String getDirectory()

Gets the directory of this file dialog.

Returns:String

the (potentially null or invalid) directory of this FileDialog

See Also
java.awt.FileDialog#setDirectory
getFileback to summary
public String getFile()

Gets the selected file of this file dialog. If the user selected CANCEL, the returned file is null.

It is platform-specific as to what happens for LOAD mode of a non-existent file. For example, it may be possible for the user to "accept" the result of a setFile value or to edit in the name of some other file to load/open even if it is not present. Applications should therefore verify the file represented by the returned String exists. The value is usually the basename, not a full path name.

Returns:String

the currently selected file of this file dialog window, or null if none is selected

See Also
java.awt.FileDialog#setFile
getFilenameFilterback to summary
public FilenameFilter getFilenameFilter()

Determines this file dialog's filename filter. A filename filter allows the user to specify which files appear in the file dialog window. Filename filters do not function in Sun's reference implementation for Microsoft Windows.

Returns:FilenameFilter

this file dialog's filename filter

See Also
java.io.FilenameFilter, java.awt.FileDialog#setFilenameFilter
getFilesback to summary
public File[] getFiles()

Returns files that the user selects.

If the user cancels the file dialog, then the method returns an empty array.

Returns:File[]

files that the user selects or an empty array if the user cancels the file dialog.

Since
1.7
See Also
setFile(String), getFile
getModeback to summary
public int getMode()

Indicates whether this file dialog box is for loading from a file or for saving to a file.

Returns:int

the mode of this file dialog window, either FileDialog.LOAD or FileDialog.SAVE

See Also
java.awt.FileDialog#LOAD, java.awt.FileDialog#SAVE, java.awt.FileDialog#setMode
isMultipleModeback to summary
public boolean isMultipleMode()

Returns whether the file dialog allows the multiple file selection.

Returns:boolean

true if the file dialog allows the multiple file selection; false otherwise.

Since
1.7
See Also
setMultipleMode
paramStringback to summary
protected String paramString()

Overrides java.awt.Dialog.paramString.

Returns a string representing the state of this FileDialog window. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Returns:String

the parameter string of this file dialog window

postsOldMouseEventsback to summary
pack-priv boolean postsOldMouseEvents()

Overrides java.awt.Container.postsOldMouseEvents.

readObjectback to summary
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException

Hides java.awt.Dialog.readObject.

Reads the ObjectInputStream and performs a backwards compatibility check by converting either a dir or a file equal to an empty string to null.

Parameters
s:ObjectInputStream

the ObjectInputStream to read

Annotations
@Serial
Exceptions
ClassNotFoundException:
if the class of a serialized object could not be found
IOException:
if an I/O error occurs
setDirectoryback to summary
public void setDirectory(String dir)

Sets the directory of this file dialog window to be the specified directory. Specifying a null or an invalid directory implies an implementation-defined default. This default will not be realized, however, until the user has selected a file. Until this point, getDirectory() will return the value passed into this method.

Specifying "" as the directory is exactly equivalent to specifying null as the directory.

Parameters
dir:String

the specified directory

See Also
java.awt.FileDialog#getDirectory
setFileback to summary
public void setFile(String file)

Sets the selected file for this file dialog window to be the specified file. This file becomes the default file if it is set before the file dialog window is first shown.

When the dialog is shown, the specified file may be pre-selected. The visible manifestation of this selection, if any, depends on factors such as the file existence, the dialog mode, and the native platform. For example, the file could be highlighted in the file list, or a file name editbox could be populated with the file name.

This method accepts either a full file path, or a file name with an extension if used together with the setDirectory method. It is platform-specific how a full file path interacts with setDirectory. It may be that the directory is always used instead of the file path, or the file path overrides the directory, or even that the full file path is interpreted as a base file name. Therefore, it is strongly recommended to use setDirectory to set the folder and setFile to set a base file name.

Appearance and behaviours may also differ between LOAD and SAVE modes.

It is also platform-specific as to what happens for LOAD mode of a non-existent file. For example, it may be possible for the user to "accept" the setFile value or to edit in the name of some other file to load/open even if it is not present.

Specifying "" as the file is exactly equivalent to specifying null as the file.

Parameters
file:String

the file being set

See Also
getFile, getFiles
setFilenameFilterback to summary
public synchronized void setFilenameFilter(FilenameFilter filter)

Sets the filename filter for this file dialog window to the specified filter. Filename filters do not function in Sun's reference implementation for Microsoft Windows.

Parameters
filter:FilenameFilter

the specified filter

See Also
java.io.FilenameFilter, java.awt.FileDialog#getFilenameFilter
setFilesback to summary
private void setFiles(File[] files)

Stores the names of all the files that the user selects. Note that the method is private and it's intended to be used by the peers through the AWTAccessor API.

Parameters
files:File[]

the array that contains the short names of all the files that the user selects.

Since
1.7
See Also
getFiles
setModeback to summary
public void setMode(int mode)

Sets the mode of the file dialog. If mode is not a legal value, an exception will be thrown and mode will not be set.

Parameters
mode:int

the mode for this file dialog, either FileDialog.LOAD or FileDialog.SAVE

Exceptions
IllegalArgumentException:
if an illegal file dialog mode is supplied
Since
1.1
See Also
java.awt.FileDialog#LOAD, java.awt.FileDialog#SAVE, java.awt.FileDialog#getMode
setMultipleModeback to summary
public void setMultipleMode(boolean enable)

Enables or disables multiple file selection for the file dialog.

Multiple mode may be ignored in some cases, for example, commonly SAVE mode dialogs do not support it.

Parameters
enable:boolean

if true, multiple file selection is enabled; false - disabled.

Since
1.7
See Also
isMultipleMode
setTitleback to summary
public void setTitle(String title)

Overrides java.awt.Dialog.setTitle.

Doc from java.awt.Dialog.setTitle.

Sets the title of the Dialog.

Note

Some platforms may not support showing the user-specified title in a file dialog. In this situation, either no title will be displayed in the file dialog's title bar or, on some systems, the file dialog's title bar will not be displayed.

Annotations
@Override