File Request 2

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

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 FileRequester plug-in class.

Global Call

   LWFileActivateFunc *filereq;
   filereq = global( LWFILEACTIVATEFUNC_GLOBAL, 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 string used to filter the filenames displayed in the dialog. This is one of the type names listed in the document for the File Type Pattern global, rather than a literal filter.

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()

A callback function you 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. Each time your pickName is called, your LWFileReqLocal structure will contain the next name in the list of names selected by the user. Your LWFileReqLocal therefore needs to be declared in a place where it will be visible to your pickName function.

Example

This code fragment asks the user for the name of an image 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( LWFILEACTIVATEFUNC_GLOBAL, GFUSE_TRANSIENT );
   if ( !filereq ) goto NoFileReq;  /* global calls can fail */

   frloc.reqType  = FREQ_SAVE; 
   frloc.title    = "Save Image";
   frloc.bufLen   = MAXFILESZ;
   frloc.pickName = NULL;
   frloc.fileType = "Images";
   frloc.path     = path;
   frloc.baseName = node;
   frloc.fullName = name;

   strcpy( frloc.path, "MyImages" );     /* a relative path */
   strcpy( frloc.baseName, "foo" );      /* a default name  */

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