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( long 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
andfullName
strings. When writing to these strings, the file request plug-in should not write more thanbufLen
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 isFREQ_MULTILOAD
, even if only one file is selected. For each call, thebaseName
,path
andfullName
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.