f$ = FileRequest(title$[, t])

f$ = FileRequest(title$[, filter$, mode, defdir$, deffile$])

FileRequest() supports many optional arguments. Before Hollywood 9.0, those had to be passed as optional parameters (see above). Since Hollywood 9.0, however, it is recommended to use the new syntax, which has a single optional table argument that can be used to pass one or more optional arguments to FileRequest().

The following table fields are recognized by this function:

Mode:

This table tag allows you to put the requester into save or multiselect mode. For save mode, pass #REQ_SAVEMODE and for multiselect mode pass #REQ_MULTISELECT. If you use multiselect mode, this function will not return a string but a table that contains all the files the user selected terminated by an empty string. Starting with Hollywood 6.0 you can also set the flag #REQ_HIDEICONS if you want to have *.info files hidden on AmigaOS. Note that #REQ_HIDEICONS is a flag that can be combined with the other modes by ORing it into a bitmask. #REQ_HIDEICONS is only supported on AmigaOS. (V2.0)

Path:

This table tag can be used to specify the initial path for the file requester. (V3.0)

File:

This table tag can be used to specify the initial file for the file requester. (V3.0)

Filters:

This table tag can be used to specify filters that define which files should be shown in the requester. This can either be a string or a table.

If it is a string, it must contain the extensions of the files that should be shown in the requester. These extensions must be separated by '|' characters. For example: "voc|wav|8svx|16sv|iff|aiff" will only show files which have one of those extensions. Make sure not to include the . before the file extension but just the actual extension. The default is "*" which means that all files should be shown.

Starting with Hollywood 9.0, you can also set Filters to a table to define individual groups of files and a description for each group. To do this, set Filters to a table that contains an arbitrary number of subtables, each describing a single group of files. Each subtable must contain the following items:

Filter:

A string containing the file extensions of this group. This string must be in the same format as described above, i.e. the individual extensions must be separated by the vertical bar character (|), for example "jpg|jpeg".

Description:

A string describing the filter group, e.g. "JPEG images".

HideFilter:

This table item is optional. If you set it to True, FileRequest() won't show the individual file extensions that belong to the filter group but just its description. Note that not all platforms support this. Defaults to False.

X:

Initial x-position for the file requester on the screen. Not all platforms support this. (V9.0)

Y:

Initial y-position for the file requester on the screen. Not all platforms support this. (V9.0)

Width:

Initial width for the file requester dialog. Not all platforms support this. (V9.0)

Height:

Initial height for the file requester dialog. Not all platforms support this. (V9.0)

title$

title for the requester; pass an empty string ("") to use the default title

t

optional: table containing further arguments (see above) (V9.0)

f$

the user's selection or an empty string if the requester was cancelled; if the requester was opened in multi-select mode, a table containing all files will be returned

f$ = FileRequest("Select a picture", {Filters = "png|jpg|jpeg|bmp"})
If f$ = ""
  Print("Requester cancelled!")
Else
  Print("Your selection:", f$)
EndIf

files = FileRequest("Select some files", {Mode = #REQ_MULTISELECT})
If files[0] = ""
  Print("Requester cancelled!")
Else
  NPrint("Path:", PathPart(files[0]))
  NPrint("Files selected:", ListItems(files) - 1)
  While files[c] <> ""
    NPrint(FilePart(files[c]))
    c = c + 1
  Wend
EndIf

f$ = FileRequest("Select file", {
  {Description = "Image files", Filter = "png|jpg|jpeg|bmp"},
  {Description = "Audio files", Filter = "wav|mp3|mp4"},
  {Description = "All files", Filter = "*"}
})