Package ca.corbett.forms.fields

Class FileField

java.lang.Object
ca.corbett.forms.fields.FormField
ca.corbett.forms.fields.FileField
All Implemented Interfaces:
EventListener, DocumentListener
public final class FileField extends FormField implements DocumentListener
A FormField for choosing a single directory or file. For directories, the chosen directory must exist. For files, you can specify whether to browse for files that must exist, or for files that must NOT exist (for example, for a save dialog).

The underlying JFileChooser is not directly exposed, but there are some convenience methods here, like setFileFilter(), that can be used to customize it.

Since:
2019-11-24
Author:
scorbo2

  • Constructor Details

    • FileField

      public FileField(String label, File initialValue, int cols, FileField.SelectionType selectionType)
      Creates a FileField with the given parameters.
      Parameters:
      label - The label to use for this field.
      initialValue - The initial File to display in the field.
      cols - The number of columns to use for the text box.
      selectionType - See SelectionType for details.

    • FileField

      public FileField(String label, File initialValue, int cols, FileField.SelectionType selectionType, boolean allowBlank)
      Creates a FileField with the given parameters.
      Parameters:
      label - The label to use for this field.
      initialValue - The initial File to display in the field.
      cols - The number of columns to use for the text box.
      selectionType - See SelectionType for details.
      allowBlank - whether to allow blank values in the field.

  • Method Details

    • setSelectionType

      public FileField setSelectionType(FileField.SelectionType selectionType)
      Sets the SelectionType for this FieldField.
      • ExistingDirectory: You can browse for a directory, which must exist and be readable/writable.
      • ExistingFile: You can browse for a single file, which must exist and be readable/writable.
      • NonExistingFile: You can browse for a single file, which must not exist (eg. for a save dialog).
      Parameters:
      selectionType - A SelectionType value as explained above.

    • setSelectionType

      public FileField setSelectionType(FileField.SelectionType selectionType, boolean allowBlankValues)
      Sets the SelectionType for this FileField.
      • ExistingDirectory: You can browse for a directory, which must exist and be readable/writable.
      • ExistingFile: You can browse for a single file, which must exist and be readable/writable.
      • NonExistingFile: You can browse for a single file, which must not exist.
      Parameters:
      selectionType - A SelectionType value as explained above.
      allowBlankValues - If false, the text field cannot be blanked out (i.e. no file specified at all).

    • getSelectionType

      public FileField.SelectionType getSelectionType()
      Returns the SelectionType of this FileField.
      Returns:
      The current SelectionType of this field. Use setSelectionType to modify.

    • setFileHidingEnabled

      public FileField setFileHidingEnabled(boolean enabled)
      If true (the default value), hidden files will not be displayed in the file chooser.

    • isFileHidingEnabled

      public boolean isFileHidingEnabled()
      Reports whether hidden files are kept out of the file chooser. The default value is true, meaning hidden files are NOT shown in the file chooser.

    • setAccessory

      public FileField setAccessory(JComponent component)
      Sets an optional "accessory" component which can be used to show custom file previews. The default value is null. Any JComponent may be given here, but your JComponent needs to implement PropertyChangeListener and respond to the SELECTED_FILE_CHANGED_PROPERTY message. See the ImagePreviewAccessory class for an example implementation.

      Note: if your component does not implement PropertyChangeListener, it won't be wired up properly, and it won't be able to preview anything.

    • getAccessory

      public JComponent getAccessory()
      Returns the accessory component associated with the file chooser, if one is set. The default value is null.

    • setAcceptAllFileFilterUsed

      public FileField setAcceptAllFileFilterUsed(boolean enable)
      If true (the default value), the file chooser will automatically get an "All files" file filter in the file type dropdown, that allows selection of all files and directories. If you disable this, you should use addChoosableFileFilter and/or setFileFilter to set your own item(s) in the dropdown list of filters.

    • isAcceptAllFileFilterUsed

      public boolean isAcceptAllFileFilterUsed()
      Indicates whether the default "All files" filter is present in the list of choosable file filters. The default value is true.

    • isAllowBlankValues

      public boolean isAllowBlankValues()
      Returns whether blank values are permitted in this field. If true, and no value is specified in the text field, then getFile() will return null. If false, then the field will throw a validation error if no value is specified.

    • setAllowBlankValues

      public FileField setAllowBlankValues(boolean allow)
      Specifies whether blank values should be allowed in the text field. If false, a non-blank validator will be added automatically.

    • setEnabled

      public FormField setEnabled(boolean enabled)
      Overridden so we can enable/disable our choose button also.
      Overrides:
      setEnabled in class FormField
      Parameters:
      enabled - whether to enable or disable the components.

    • getTextField

      public JTextField getTextField()
      Allows direct access to the underlying JTextField.

    • getFile

      public File getFile()
      Returns the currently selected File from this field.
      Returns:
      A File object.

    • setFile

      public FileField setFile(File file)
      Sets the currently selected File for this field.
      Parameters:
      file - The File to select.

    • addChoosableFileFilter

      public FileField addChoosableFileFilter(FileFilter filter)
      Adds a FileFilter to the list of user-selectable filters on the dialog. You can use setFileFilter to specify which of the filters should be selected by default. Note that by default, the file chooser will also add a "All files" filter to the list, and that one will be selected by default unless you invoke setFileFilter. You can disable the "All files" filter via setAcceptAllFileFilterUsed, but if you do that, you should invoke setFileFilter to set the default (otherwise it'll just be the first in the list).

    • removeChoosableFileFilter

      public FileField removeChoosableFileFilter(FileFilter filter)
      Removes the given FileFilter from the list of choosable filters that were provided via addChoosableFileFilter.

    • resetChoosableFileFilters

      public FileField resetChoosableFileFilters()
      Resets the list of choosable file filters back to the starting state.

    • setFileFilter

      public FileField setFileFilter(FileFilter filter)
      Sets which of the choosable file filters added via addChoosableFileFilter should be selected by default when the dialog comes up. If the filter that you supply here isn't already in the list, it will be added to this list. This method can therefore be a bit of a shortcut if you only have one filter for your dialog.
      Parameters:
      filter - An optional FileFilter to apply.

    • getFileFilter

      public FileFilter getFileFilter()
      Returns the currently selected FileFilter in the dialog. This can either be the built-in All files filter (if isAcceptAllFileFilterUsed is true), or one of the filters supplied to addChoosableFileFilter.

    • preRender

      public void preRender(JPanel container)
      Description copied from class: FormField
      Invoke before rendering this FormField to a container, in case the FormField needs to do some initialization specific to its new container (for example, matching the container's background color or using the container as a parent component for a popup dialog). The default implementation here does nothing. Overriding this method is optional.
      Overrides:
      preRender in class FormField

    • addFieldValidator

      public FormField addFieldValidator(FieldValidator<? extends FormField> validator)
      Overridden so that it acts only on our "user-added" validators list. We need to keep these separate from the validators that we add internally depending on selectionType.
      Overrides:
      addFieldValidator in class FormField

    • removeFieldValidator

      public void removeFieldValidator(FieldValidator<FormField> validator)
      Overridden so that it acts only on our "user-added" validators list. We need to keep these separate from the validators that we add internally depending on selectionType.
      Overrides:
      removeFieldValidator in class FormField

    • removeAllFieldValidators

      public void removeAllFieldValidators()
      Overridden so that it acts only on our "user-added" validators list. We need to keep these separate from the validators that we add internally depending on selectionType.
      Overrides:
      removeAllFieldValidators in class FormField

    • insertUpdate

      public void insertUpdate(DocumentEvent e)
      Specified by:
      insertUpdate in interface DocumentListener

    • removeUpdate

      public void removeUpdate(DocumentEvent e)
      Specified by:
      removeUpdate in interface DocumentListener

    • changedUpdate

      public void changedUpdate(DocumentEvent e)
      Specified by:
      changedUpdate in interface DocumentListener