The V C++ GUI Framework:vFileSelect

From EDM2
Jump to: navigation, search

A utility class to select or set a file name.

Synopsis

Header
<v/vfilesel.h>
Class name
vFileSelect
Hierarchy
vModalDialog ->vFileSelect

Description

This utility class provides a dialog interface for selecting filenames. It can be used either to select an input file name, or verify or change an output file name. This utility does not open or alter files - it simply constructs a legal file name for use in opening a file.

Methods

vFileSelect(vBaseWindow* win)
vFileSelect(vApp* app)

The vFileSelect constructor requires a pointer to a vBaseWindow, which includes all V windows and dialogs, or a pointer to the vApp object. You will usually pass the this to the constructor.

int FileSelect(const char* prompt, char* filename, const int maxLen,
               char** filterList, int& filterIndex)
int FileSelectSave(const char* prompt, char* filename, const int maxLen,
                   char** filterList, int& filterIndex)

You provide a prompt for the user, such as Open File. The user then uses the dialog to select or set a file name. FileSelect returns True if the user picked the OK button, and False if they used the Cancel button.

The filename will be filled in to the filename buffer of maximum length maxLen. The full path of the file will be included with the file name.

You can also provide a list of filter patterns to filter file extensions. If you don't provide a filter list, the default filter of * will be used. Each item in the filter list can include a list of file extensions separated by blanks. You can provide several filtering options. The first filter in the list will be the default. Only leading * wild cards are supported.

The filterIndex reference parameter is used to track which filter the user selected. After FileSelect returns, filterIndex will be set to the index of the filter list that the user last selected. For the best interface, you should remember this value for the next time you call FileSelect with the same filter list so that the user selected filter will be preserved.

You should use FileSelect to open a new or existing file. If the user is being asked to save a file (usually after picking a Save As menu choice), use the FileSelectSave method. On some platforms, there will be no difference between these two methods (X, for example). On other platforms (Windows, for example), different underlying system provided file dialogs are used. To your program, there will be no difference in functionality.

Example

The following is a simple example of using vFileSelect.

V-filesel.gif

    static char* filter[] =     // define a filter list
      {
        "*",                    // all files
        "*.txt",                // .txt files
        "*.c *.cpp *.h",        // C sources
        0
      };
    static int filterIndex = 0;    // to track filter picked
    char name[100];

    vFileSelect fsel(this);     // instantiate

    int oans = fsel.FileSelect("Open file",name,99,filter,filterIndex);

    vNoticeDialog fsnote(this); // make an instance

    if (oans && *name)
        (void)fsnote.Notice(name);
    else
        (void)fsnote.Notice("No file name input.");