tsc_FilenameField

This is a text input control for forms, based on tsc_Control.

The purpose of this field is to allow the user to enter a file name.  The directory part of the filename is not displayed.  There are no enforced

requirements that the file exists. The context menu (the small button to the right) of this field allows access to a file selection dialog where the user can choose from existing files or folders.  A file or folder from a subfolder can be chosen, but the user cannot browse upwards (towards the filesystem root).

Constructor

In the constructor it is possible to specify:

• • Whether the user is able to select a folder or a file with the context menu.

  • The directory for the file, which is also the root folder of the browsing dialog.

  • An array of the acceptable file types such as "*.csv".

enum FilenameContextMenuType

{

    MenuTypeSelectFile = 0,

    MenuTypeSelectFolder

};

This enum controls how the file/folder open dialog behaves:

• • To open an existing file, use MenuTypeSelectFile; this allows the user to enter a filename, or to press the button and navigate to any folder in or below the specified rootFolder and select an existing file.

  • For creating a new file, use MenuTypeSelectFolder; this allows the user to enter any filename into the field, and optionally press the button to navigate to any folder in or below the specified rootFolder.  The selected folder becomes the folder returned by the GetFolder and GetFullPath methods.

tsc_FilenameField (x_Code                  prompt,      // The field prompt and identifier.

                   const char*             filename,    // Initial file name, with or without a directory part.

                   FilenameContextMenuType menuType,    // Whether a folder or a file is able to be selected.

                   const char*             rootFolder,  // The default folder and also the root folder for file browsing.

                   const tsc_StringList&   fileTypes);  // The file types allowed (eg, *.csv, *.job, etc)

See the Value member function for more information about the filename parameter.

The rootFolder parameter becomes the default folder for the file unless overidden by a folder name on the front of the supplied filename.

Since version 20.20:

If the filename parameter is just a filename or contains a relative path, then rootFolder is added to the front. If filename contains an absolute path, then that path is used and if the rootFolder is not somewhere on that path then it will be adjusted to be the same. 

And to clarify, the rootFolder parameter determines the uppermost level in the directory tree that the user can browse to. This makes the directory tree quicker to load, smaller, and easier to use. The user can still 'escape' from the root folder by manually typing an absolute path into the filename field.

Member Functions

The "value" of this field is a filename, and it may be set using the Value method, or using the filename parameter in the constructor.  A folder part may be present in the file name.  If the folder part is relative, it is relative to the rootFolder specified in the constructor.  If absolute, it must lie within the rootFolder; if not, then the directory part is discarded and replaced by the rootFolder.

void Value(const char* newText);

The text of the field.  This value contains the file name only, the rest of the path is excluded, even if it was specified in the constructor or by calling the Value setter method.  These two functions are equivalent.

tsc_String Value() const;

tsc_String GetFileNameNoPath() const;

Returns the directory name.

tsc_String GetFolder() const;

Returns the directory and file name.

tsc_String GetFullPath() const;

This methods control whether the user can set the contents to empty/NULL values.

virtual void AllowEmpty   (bool allowEmpty);

virtual bool EmptyAllowed () const;

Example of usage:

Note that the full path of the file will initially be: $(ProjectRootDir)\csvFiles\default.csv

The user can change the filename (default.csv) by entering a new name into the field, or they can change the folder by pressing the folder button beside the field and selecting a new folder in or below the ProjectRootDir folder.

void MyForm::OnFormLoad() {     this->Controls.Add (new tsc_FilenameField (                                   X_FileName,                                   "csvFiles\default.csv",                                   tsc_FilenameField::MenuTypeSelectFolder,                                   "$(ProjectRootDir)",                                   tsc_StringList("*.csv", "*.txt"))                         ); }