FileRequester

Availability  LightWave® 6.0
Component  Layout, Modeler
Header  lwdialog.h

File request plug-ins prompt the user for a file selection. At a minimum, they should provide the same functionality as the operating system's default file dialog, allowing users to browse their file systems to select or enter a file name.

See the File Request 2 global for a discussion of file requests from the host's point of view.

Handler Activation Function

   XCALL_( int ) MyFileReq( int version, GlobalFunc *global,
      LWFileReqLocal *local, void *serverData );

The local argument to a file request plug-in's activation function is an LWFileReqLocal.

   typedef struct st_LWFileReqLocal {
      int         reqType;
      int         result;
      const char *title;
      const char *fileType;
      char       *path;
      char       *baseName;
      char       *fullName;
      int         bufLen;
      int        (*pickName) (void);
   } LWFileReqLocal;

reqType

Indicates the type of file request. Possible values are

FREQ_LOAD

FREQ_SAVE

FREQ_DIRECTORY

A request for a path.

FREQ_MULTILOAD

A request for one or more files to load.

result

The result of the request. Set this to 1 if the user selects a file, 0 if the user cancels the request, and a negative number to indicate an error.

title

The title string. This is generally displayed near the top of the file dialog and tells the user what kind of file is being requested.

fileType

A string identifying a file type filter. This should be used to filter the names displayed in the dialog. The string will generally contain one of the file type names used in LightWave®'s configuration files, rather than a literal, platform-specific list of type IDs or wildcards. See the File Type Pattern global for more information about what the file type string might contain. You can use the global to translate this into a literal filter string.

path

The initial path on entry. This is where browsing of the file system should begin. The initial path can be either absolute (fully qualified) or relative to the operating system's current default path, also sometimes called the current working directory. If the user completes the file request, the plug-in should write the fully qualified path of the selected file in this field.

If the operation of the file request plug-in changes the current working directory, this should be restored before the file request is completed.

baseName

The initial file name, not including the path. This may be empty, or it may contain a default name. If the user selects a file, the initial name should be replaced with the name (not including the path) of the selected file.

fullName

The file request returns the selected file name, including the path, in this string. The initial contents are ignored.

bufLen

The size in bytes of the baseName, path and fullName strings. When writing to these strings, the file request plug-in should not write more than bufLen characters, including the NULL terminating byte.

error = pickName()

A callback function provided by the host for FREQ_MULTILOAD requests. This function should be called for each selected file when the request type is FREQ_MULTILOAD, even if only one file is selected. For each call, the baseName, path and fullName fields should be filled with the data for the next selected file in the list. The function returns 0 to continue and any non-zero value to stop processing the files in a multiple file selection.

Example

The wfilereq sample is a FileRequester that uses the Windows common file dialog.