"File Request 2"

Availability:  LightWave 5.5 - 6.0, Inspire 1.0
Component:  Layout, Modeler

The file request 2 global returns a function that prompts the user for a file selection. The request displays the file dialog currently installed in LightWave. This may be the default system dialog or a custom file dialog plug-in. See the "File Request" global for an alternative interface to the file dialog mechanism.

The primary advantage of this file request global over the original "File Request" is a smarter and more flexible interface to the file dialog. The dialog is initialized by filling out a structure, rather than through a limited number of function arguments.

Note that in contrast to the original, this global allows plug-ins to call the file request activation function directly. Plug-ins calling this global act as the host side of the FileRequest plug-in class.

Global Call

   LWFileActivateFunc *filereq;
   filereq = global( "File Request 2", GFUSE_TRANSIENT );

The global function returns a pointer to an LWFileActivateFunc.

   typedef int LWFileActivateFunc (int version, LWFileReqLocal *);

The return value of this function can be any of the values defined for the return values of activation functions. Any value other than AFUNC_OK must be handled as an error.

The version is passed as the version argument to the file request plug-in's activation function. This should be set to the value defined by the LWFILEREQ_VERSION symbol in lwdialog.h. File request plug-ins with a different activation version will return AFUNC_BADVERSION.

The second argument to this function is a pointer to a structure that is passed as the local argument to the file request plug-in's activation function.

The Local Structure

The file request function passes an LWFileReqLocal as the local argument to the activation function of the file request plug-in.

   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
FREQ_MULTILOAD

result

The result of the request. This will be 1 if the user selected a file, 0 if the user cancelled 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 file type pattern string. This is used to filter the names displayed in the dialog. Pattern strings for certain types of files can be obtained from the "File Type Pattern" global. If you construct your own pattern strings, remember that these are platform-specific and may also be locale-specific.

path

The initial path. Default paths for certain file types can be obtained from the "Directory Info" global. If you construct your own path string, remember that path lexics depend on the platform. If the user selects a file, the initial path is replaced with the path of the selected file.

baseName

The initial file name, not including the path. This can be empty, or it can contain a default name. The initial name can also contain wildcards that may be used to filter the names displayed in the dialog. If the user selects a file, the initial name is 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. Note that all of them must be the same size, and should be large enough to hold the largest file name you expect to process (a minimum of 256 bytes is recommended).

pickName()

An optional callback function that you should provide when making MULTILOAD requests. This function will be called for each selected file. It returns 0 to continue and any non-zero value to stop processing the files in a multiple file selection. Your LWFileRequestLocal structure needs to be visible to your pickName function if you want it to extract each file name as it's called.

Example

This code fragment asks the user for the name of a file to save.

   #include <lwserver.h>
   #include <lwhost.h>

   #define MAXFILESZ 260

   static char
      node[ MAXFILESZ ] = "",
      path[ MAXFILESZ ] = "",
      name[ MAXFILESZ ] = "";
   static LWFileReqLocal frloc;

   LWFileActivateFunc *filereq;
   int result;

   filereq = global( "File Request 2", GFUSE_TRANSIENT );
   if ( !filereq ) goto NoFileReq;  /* global calls can fail */

   frloc.reqType  = FREQ_SAVE; 
   frloc.title    = "Save Widget";
   frloc.bufLen   = MAXFILESZ;
   frloc.pickName = NULL;
   frloc.fileType = "*.wgt";            /* a Windows-specific pattern */
   strcpy( frloc.path, "Widgets" );     /* a relative path */
   strcpy( frloc.baseName, "foo.wgt" ); /* a default name */

   result = filereq( LWFILEREQ_VERSION, &frloc );
   if ( result == AFUNC_OK && frloc.result > 0 ) {
      save_widget( widget, frloc.fullName );
      ...