int error = FileRequest(APTR handle, STRPTR title, ULONG flags,
                STRPTR *result, struct hwTagList *tags);

The flags and tags parameters are used to control the appearance of the file requester. The following flags are currently defined:

HWFILEREQFLAGS_MULTISELECT:

If this flag is set, your requester has to allow the selection of multiple files. In multi-select mode the return string pointer that you write to the result parameter has to be a list of fully qualified paths to files. The individual filenames are separated from one another by a single NULL terminator byte whereas the complete list is terminated by two NULL terminator bytes to signal the list end to Hollywood. This flag cannot be combined with HWFILEREQFLAGS_SAVEMODE.

HWFILEREQFLAGS_SAVEMODE:

If this flag is set, Hollywood wants your requester to open in save mode, i.e. the user should select a file for saving. In contrast to open file mode, the user might select a file that doesn't exist when in save mode and the requester should also make the user confirm that the file can be overwritten in case he selects an existing file. This flag cannot be combined with HWFILEREQFLAGS_MULTISELECT.

Hollywood also passes a taglist to this function. Your implementation has to handle the following tags:

HWFILEREQTAG_FROMSCRIPT:

The iData member of this tag item is set to True if Hollywood has called you while the script is running. This might be important to know because requesters should not block window refresh so you might want to setup a temporary modal event loop if this tag has been set to True to enable your display to stay responsive.

HWFILEREQTAG_EXTENSIONS:

If this tag is set, the requester should only show files that use the specified file extension. The pData member of this tag item is set to a string that contains a list of file extensions that should be shown. The individual extensions do not contain a dot and are separated by a vertical bar character (|), for example "jpg|jpeg|png|bmp|gif|lbm|ilbm".

HWFILEREQTAG_DEFDRAWER:

If this tag is set, Hollywood wants your requester to show the files of this directory when it opens. The directory is passed as a string in the pData member of this tag item.

HWFILEREQTAG_DEFFILE:

If this tag is set, Hollywood wants your requester to preselect this file when it opens. The file is passed as a string in the pData member of this tag item.

HWFILEREQTAG_FILTERS:

Starting with Hollywood 9.0, FileRequest() supports the declaration of filter groups via an optional table argument. If a script passes such a filter group to FileRequest(), it will be forwarded to your plugin in this tag item. The pData member of the tag item will be set to a pointer to a struct hwFileReqFilterInfo containing the first item of the filter group and a pointer to the next item.

The struct hwFileReqFilterInfo looks like this:

struct hwFileReqFilterInfo { struct hwFileReqFilterInfo *Succ; STRPTR Description; STRPTR Filter; ULONG Flags; };

Here is a description of the structure members:

Succ:

Contains a pointer to the next node in the list or NULL for the tail node.

Description:

Contains the filter group's description.

Filter:

Contains the actual file extensions that should be part of this filter group.

Flags:

A combination of flags for this filter group. The following flags are currently defined:

HWFILEREQFILTERFLAGS_HIDE:

If this flag is set, your file requester shouldn't show the actual file extensions that are part of the group but just the group description.

(V9.0)

FileRequest() is an optional API and must only be implemented if HWSRAFLAGS_FILEREQUEST has been passed to hw_SetRequesterAdapter(). See hw_SetRequesterAdapter for details.

handle

display handle or NULL if no display is open

title

title string for the requester's window

flags

flags controlling the requester's appearance (see above)

result

STRPTR pointer for storing the user's selection

tags

taglist for additional options (see above)

error

error code or 0 for success