File Request

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

The file request 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 2 global for a newer interface to the file dialog mechanism.

Global Call

   LWFileReqFunc *filereq;
   filereq = global( LWFILEREQFUNC_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWFileReqFunc.

   typedef int LWFileReqFunc (const char *hail, char *name, char *path,
      char *fullName, int buflen);

hail

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.

name

The initial file name, not including the path. This can be empty, or it can contain a default name. It can also contain file type patterns that on most systems will 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.

Some systems display different dialogs for loading and saving. If the first character of the name is '<', a load dialog will be displayed, and if it's '>', a save dialog will be displayed. These initial characters won't appear as part of the initial name or file type pattern.

If the user selects a file, the initial name is replaced with the name (not including the path) of the selected file.

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.

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 name, path and fullName strings. Note that all of them must be at least this size and must be large enough to hold the largest file name string you expect to process (a minimum of 256 bytes is recommended).

Example

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

   #include <lwhost.h>
   #define MAXFILESZ 260

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

   LWFileReqFunc *filereq;
   LWMessageFuncs *message;
   int result;

   filereq = global( LWFILEREQFUNC_GLOBAL, GFUSE_TRANSIENT );
   message = global( LWMESSAGEFUNCS_GLOBAL, GFUSE_TRANSIENT );
   if ( !filereq || !message ) return AFUNC_BADGLOBAL;

   result = filereq( "Save Widget", node, path, name, MAXFILESZ );
   if ( result ) {
      save_widget( widget, name );
      message->info( "The widget has been saved to", node );
   }
   else
      /* the user cancelled the file dialog */
      ...