FileDialog (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.ui.FileDialog

```
public class FileDialog
extends java.lang.Object
```
A class that collects option information about a file selection statement using chained methods.
Each public method emulates an option of the statement. They do a quick validation. If successful, they return a reference to this object to allow other method to be chained.
The execute() method does the final checks, send the request with gathered options to client, awaits the user to interact and finally sets up the response and confirmation variable update.

Field Summary

Fields
Modifier and Type	Field and Description
`private boolean`	`askOverwrite` If `true`, a dialog is displayed to prompt for confirmation if the user selects the a file that already exists.
`private boolean`	`atWebBrowser` AT-WEB-BROWSER option value
`private boolean`	`createTestFile` The dialog will attempt to create a temporary file with selected name and location before it completes in order to verify whether the user has write access to respective directory.
`private java.lang.String`	`defaultExtension` The default extension to be appended to the user's selection if it does not have one.
`private java.lang.String[]`	`events` An array of legacy events registered for direct upload
`private java.lang.String[]`	`filters` Defines one or more filters for the filename dialog.
`private boolean`	`findDirectories` Flag to mark a dialog for selecting a directory.
`private java.lang.String`	`initialDir` The initial directory where dialog opens for the first time.
`private int`	`initialFilter` If `filters` are specified, then the default one is designed by this value.
`private handle`	`inWindow` Specifies the parent window for the dialog box to be displayed.
`private boolean`	`multiple` MULTIPLE option value
`private boolean`	`mustExist` Enforces that the user must select and existing file.
`private character`	`path` As input parameter, when `useFilename == true` this is the default filename presented to user.
`private boolean`	`returnToStartDir` By default, the last directory where the user has selected a file remains will be used as the default initial directory for subsequent invocations of this method.
`private boolean`	`saveAs` Converts the dialog to a "Save As..." dialog box.
`private java.lang.String`	`title` The title of the dialog.
`private logical`	`toUpdate` A logical variable used as output parameter that will contain the status of the user's dialog interaction: if the user validates it by selecting the `OK` button, the value of the variable is set to `TRUE` on return.
`private boolean`	`upload` UPLOAD option value
`private java.lang.String`	`uploadDir` Upload directory.
`private boolean`	`useFilename` Specifies the contents of `path` as the default filename entry for the dialog.
`private CommonWidget`	`widget` A reference of a widget registered for direct upload

Constructor Summary

Constructors
Modifier	Constructor and Description
`private`	`FileDialog(character path, boolean findDirs)` The constructor.
`private`	`FileDialog(CommonWidget widget, java.lang.String[] events)` Creates a new FileDialog instance.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`FileDialog`	`askOverwrite()` Configures the file selection dialog to warn the user that the selected file already exists and prompt for overwrite it.
`FileDialog`	`atWebBrowser()` Sets the AT-WEB-BROWSER option.
`static FileDialog`	`createDirSearchDialog(character dirPath)` Creates a configurable `FileDialog` object that will prompt the user to select a directory when executed.
`static FileDialog`	`createFileSearchDialog(character filePath)` Creates a configurable `FileDialog` object that will prompt the user to select a file when executed.
`FileDialog`	`createTestFile()` Configures the file selection dialog to check write access.
`void`	`deregister()` Deregisters a widget from direct upload.
`static FileDialog`	`directUpload(CommonWidget widget, java.lang.String... events)` Initializes the object with widget and an array of events for the direct upload use case.
`static FileDialog`	`directUpload(handle widget, java.lang.String... events)` Initializes the object with widget and an array of events for the direct upload use case.
`void`	`execute()` Displays the file selection dialog that was already configured.
`FileDialog`	`multiple()` Sets the MULTIPLE option.
`FileDialog`	`mustExist()` Configures the file selection dialog not to select new files.
`void`	`register()` Registers a widget with the associated set of events and other optional parameters for direct upload.
`FileDialog`	`returnToStartDir()` Configures the file selection dialog to discard any used navigation and not to save the destination directory as default location for subsequent dialogs.
`FileDialog`	`saveAs()` Configures the file selection dialog as a Save-as dialog.
`FileDialog`	`setDefaultExtension(character defaultExtension)` Configures the default extension of the file selection dialog.
`FileDialog`	`setDefaultExtension(java.lang.String defaultExtension)` Configures the default extension of the file selection dialog.
`FileDialog`	`setFilters(java.lang.Object... filters)` Configures the filters of the file selection dialog.
`FileDialog`	`setInitialDir(BaseDataType initialDir)` Configures the initial directory where the file selection dialog is open.
`FileDialog`	`setInitialDir(character initialDir)` Configures the initial directory where the file selection dialog is open.
`FileDialog`	`setInitialDir(java.lang.String initialDir)` Configures the initial directory where the file selection dialog is open.
`FileDialog`	`setInitialFilter(long initialFilter)` Configures the initial filter of the file selection dialog.
`FileDialog`	`setInitialFilter(NumberType initialFilter)` Configures the initial filter of the file selection dialog.
`FileDialog`	`setTitle(character title)` Configures the title of the file selection dialog.
`FileDialog`	`setTitle(java.lang.String title)` Configures the title of the file selection dialog.
`FileDialog`	`setWindow(handle window)` Configures the file dialog to be created as child of a certain windows.
`FileDialog`	`update(logical update)` Configures the variable to be set when the file selection dialog is closed.
`FileDialog`	`upload()` Sets the UPLOAD flag.
`FileDialog`	`upload(character dir)` Sets the UPLOAD flag and assigns the upload directory.
`FileDialog`	`upload(java.lang.String dir)` Sets the UPLOAD flag and assigns the upload directory.
`FileDialog`	`useFilename()` Configures the file selection dialog to use the current value of the `path` as default filename and location.
`private static void`	`validateParam(BaseDataType param)` Validates a parameter.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - findDirectories
```
private boolean findDirectories
```
    Flag to mark a dialog for selecting a directory. If true the user can select only directories. If false the user can select only files.
  - path
```
private character path
```
    As input parameter, when useFilename == true this is the default filename presented to user. When the dialog finished with success it contains the filename the user has selected - as OUTPUT parameter. When multiple is set, the variable will be set to comma separated list of files/paths.
  - toUpdate
```
private logical toUpdate
```
    A logical variable used as output parameter that will contain the status of the user's dialog interaction: if the user validates it by selecting the OK button, the value of the variable is set to TRUE on return. If the user rejects the dialog by pressing the Cancel button, the variable's value on return will be FALSE.
  - inWindow
```
private handle inWindow
```
    Specifies the parent window for the dialog box to be displayed. The value must be a handle to a window.
  - title
```
private java.lang.String title
```
    The title of the dialog. This is optional. If not provided default titles for Open and Save As dialogs will be used.
  - askOverwrite
```
private boolean askOverwrite
```
    If true, a dialog is displayed to prompt for confirmation if the user selects the a file that already exists. This option is used only if SAVE-AS option is also active.
  - createTestFile
```
private boolean createTestFile
```
    The dialog will attempt to create a temporary file with selected name and location before it completes in order to verify whether the user has write access to respective directory. On error, the user is notified by a message and user is prompted to select another filename. The dialog will complete when the user enters a filename associated with a writable directory or completely rejects the dialog. The intermediary file is deleted.
    Note: this option is not supported yet.
  - defaultExtension
```
private java.lang.String defaultExtension
```
    The default extension to be appended to the user's selection if it does not have one.
  - initialDir
```
private java.lang.String initialDir
```
    The initial directory where dialog opens for the first time.
  - mustExist
```
private boolean mustExist
```
    Enforces that the user must select and existing file. If (s)he chooses otherwise, an error message is displayed and he is requested to select another filename. The dialog does not complete until the user selected an existing file or uses Cancel button to reject the dialog.
  - returnToStartDir
```
private boolean returnToStartDir
```
    By default, the last directory where the user has selected a file remains will be used as the default initial directory for subsequent invocations of this method. When the option is specified, the selected directory is not saved. It has no effect if subsequent invocations that specify the INITIAL-DIR option.
  - saveAs
```
private boolean saveAs
```
    Converts the dialog to a "Save As..." dialog box.
  - useFilename
```
private boolean useFilename
```
    Specifies the contents of path as the default filename entry for the dialog. The user is free to change it if needed.
  - initialFilter
```
private int initialFilter
```
    If filters are specified, then the default one is designed by this value.
  - filters
```
private java.lang.String[] filters
```
    Defines one or more filters for the filename dialog. Each filter selects a subset of the available files in the common dialog directory to build the dialog file selection-list. A filter consists of two parts: a label (name) and file specification (filespec). Must be an even size array.
  - atWebBrowser
```
private boolean atWebBrowser
```
    AT-WEB-BROWSER option value
  - upload
```
private boolean upload
```
    UPLOAD option value
  - multiple
```
private boolean multiple
```
    MULTIPLE option value
  - uploadDir
```
private java.lang.String uploadDir
```
    Upload directory. Ony relevant when UPLOAD option is given.
  - widget
```
private CommonWidget widget
```
    A reference of a widget registered for direct upload
  - events
```
private java.lang.String[] events
```
    An array of legacy events registered for direct upload
- Constructor Detail
  - FileDialog
```
private FileDialog(character path,
                   boolean findDirs)
```
    The constructor. Configures the dialog in the simplest form when only the path reference is passed. To activate it, just call execute. Depending on the findDirs flag, some of the options to be set may not be valid (FILTERS, INITIAL-FILTER, DEFAULT-EXTENSION, MUST-EXIST, CREATE-TEST-FILE, SAVE-AS, ASK-OVERWRITE, USE-FILENAME and UPDATE are not valid when findDirs == false).
    
    Parameters:
    
    path - A reference to a character variable to be updated if the dialog is accepted.
    
    findDirs - Sets the type of file dialog. If true this will select folders only (behave like the SYSTEM-DIALOG-GET-DIR), otherwise, only files are allowed to be returned (behave like the SYSTEM-DIALOG-GET-FILE).
  - FileDialog
```
private FileDialog(CommonWidget widget,
                   java.lang.String[] events)
```
    Creates a new FileDialog instance. This constructor is used for the direct upload use case.
    
    Parameters:
    
    widget - the widget object to associate the FileDialog with
    
    events - the array of events to associate the FileDialog with
- Method Detail
  - createFileSearchDialog
```
public static FileDialog createFileSearchDialog(character filePath)
```
    Creates a configurable FileDialog object that will prompt the user to select a file when executed.
    
    Parameters:
    
    filePath - The output parameter that will contain result (full absolute path).
    
    Returns:
    
    A FileDialog that can be configured with various options using chained methods before calling execute() to be displayed.
  - createDirSearchDialog
```
public static FileDialog createDirSearchDialog(character dirPath)
```
    Creates a configurable FileDialog object that will prompt the user to select a directory when executed.
    
    Parameters:
    
    dirPath - The output parameter that will contain result (full absolute path).
    
    Returns:
    
    A FileDialog that can be configured with various options using chained methods before calling execute() to be displayed.
  - directUpload
```
public static FileDialog directUpload(CommonWidget widget,
                                      java.lang.String... events)
```
    Initializes the object with widget and an array of events for the direct upload use case.
    
    Parameters:
    
    widget - the CommonWidget to associate the file dialog with
    
    events - the array of events to associate the FileDialog with
    
    Returns:
    
    the created FileDialog instance
  - directUpload
```
public static FileDialog directUpload(handle widget,
                                      java.lang.String... events)
```
    Initializes the object with widget and an array of events for the direct upload use case.
    
    Parameters:
    
    widget - a handle of a CommonWidget to associate the file dialog with
    
    events - the array of events to associate the FileDialog with
    
    Returns:
    
    the created FileDialog instance
  - setWindow
```
public FileDialog setWindow(handle window)
```
    Configures the file dialog to be created as child of a certain windows.
    
    Parameters:
    
    window - A handle to a window that will be the parent of the dialog. The handle must refer a window or an error condition will be issued.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    inWindow
  - setTitle
```
public FileDialog setTitle(character title)
```
    Configures the title of the file selection dialog.
    
    Parameters:
    
    title - The title of the file selection dialog.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    title
  - setTitle
```
public FileDialog setTitle(java.lang.String title)
```
    Configures the title of the file selection dialog.
    
    Parameters:
    
    title - The title of the file selection dialog.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    title
  - askOverwrite
```
public FileDialog askOverwrite()
```
    Configures the file selection dialog to warn the user that the selected file already exists and prompt for overwrite it.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    askOverwrite
  - createTestFile
```
public FileDialog createTestFile()
```
    Configures the file selection dialog to check write access.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    createTestFile
  - setDefaultExtension
```
public FileDialog setDefaultExtension(character defaultExtension)
```
    Configures the default extension of the file selection dialog.
    
    Parameters:
    
    defaultExtension - The default extension for selected file.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    defaultExtension
  - setDefaultExtension
```
public FileDialog setDefaultExtension(java.lang.String defaultExtension)
```
    Configures the default extension of the file selection dialog.
    
    Parameters:
    
    defaultExtension - The default extension for selected file.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    defaultExtension
  - setInitialDir
```
public FileDialog setInitialDir(BaseDataType initialDir)
```
    Configures the initial directory where the file selection dialog is open.
    
    Parameters:
    
    initialDir - the initial directory where the file selection dialog is open.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    initialDir
  - setInitialDir
```
public FileDialog setInitialDir(character initialDir)
```
    Configures the initial directory where the file selection dialog is open.
    
    Parameters:
    
    initialDir - the initial directory where the file selection dialog is open.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    initialDir
  - setInitialDir
```
public FileDialog setInitialDir(java.lang.String initialDir)
```
    Configures the initial directory where the file selection dialog is open.
    
    Parameters:
    
    initialDir - the initial directory where the file selection dialog is open.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    initialDir
  - mustExist
```
public FileDialog mustExist()
```
    Configures the file selection dialog not to select new files.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    mustExist
  - returnToStartDir
```
public FileDialog returnToStartDir()
```
    Configures the file selection dialog to discard any used navigation and not to save the destination directory as default location for subsequent dialogs.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    returnToStartDir
  - saveAs
```
public FileDialog saveAs()
```
    Configures the file selection dialog as a Save-as dialog.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    saveAs
  - useFilename
```
public FileDialog useFilename()
```
    Configures the file selection dialog to use the current value of the path as default filename and location.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    useFilename
  - update
```
public FileDialog update(logical update)
```
    Configures the variable to be set when the file selection dialog is closed.
    
    Parameters:
    
    update - A variable that will hold the return status of the dialog. That is true if the dialog was accepted and false otherwise.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    toUpdate
  - setInitialFilter
```
public FileDialog setInitialFilter(long initialFilter)
```
    Configures the initial filter of the file selection dialog.
    
    Parameters:
    
    initialFilter - The index of the initial filter.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    initialFilter
  - setInitialFilter
```
public FileDialog setInitialFilter(NumberType initialFilter)
```
    Configures the initial filter of the file selection dialog.
    
    Parameters:
    
    initialFilter - The index of the initially active filter.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    initialFilter
  - setFilters
```
public FileDialog setFilters(java.lang.Object... filters)
```
    Configures the filters of the file selection dialog. Only files of the active filter type will be visible for selection. User is free to choose any of them as active.
    
    Parameters:
    
    filters - The list of filters for the file selection dialog.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
    
    See Also:
    
    filters
  - multiple
```
public FileDialog multiple()
```
    Sets the MULTIPLE option.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
  - atWebBrowser
```
public FileDialog atWebBrowser()
```
    Sets the AT-WEB-BROWSER option.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
  - upload
```
public FileDialog upload()
```
    Sets the UPLOAD flag.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
  - upload
```
public FileDialog upload(character dir)
```
    Sets the UPLOAD flag and assigns the upload directory.
    
    Parameters:
    
    dir - The upload directory.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
  - upload
```
public FileDialog upload(java.lang.String dir)
```
    Sets the UPLOAD flag and assigns the upload directory.
    
    Parameters:
    
    dir - The upload directory.
    
    Returns:
    
    The reference to current FileDialog. Used for chaining.
  - execute
```
public void execute()
```
    Displays the file selection dialog that was already configured. The dialog box allows the user to enter a filename that is assigned to a character variable. The method provides a dialog box appropriate to the environment in which it runs.
  - register
```
public void register()
```
    Registers a widget with the associated set of events and other optional parameters for direct upload.
  - deregister
```
public void deregister()
```
    Deregisters a widget from direct upload.
  - validateParam
```
private static void validateParam(BaseDataType param)
```
    Validates a parameter. The BDT parameters for all options must not be null or unknown.
    
    Parameters:
    
    param - The parameter to check.
    
    Throws:
    
    ErrorConditionException - if the parameter does not meet the requirements.

Class FileDialog

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

findDirectories

path

toUpdate

inWindow

title

askOverwrite

createTestFile

defaultExtension

initialDir

mustExist

returnToStartDir

saveAs

useFilename

initialFilter

filters

atWebBrowser

upload

multiple

uploadDir

widget

events

Constructor Detail

FileDialog

FileDialog

Method Detail

createFileSearchDialog

createDirSearchDialog

directUpload

directUpload

setWindow

setTitle

setTitle

askOverwrite

createTestFile

setDefaultExtension

setDefaultExtension

setInitialDir

setInitialDir

setInitialDir

mustExist

returnToStartDir

saveAs

useFilename

update

setInitialFilter

setInitialFilter

setFilters

multiple

atWebBrowser

upload

upload

upload

execute

register

deregister

validateParam