$Id: Files.txt,v 1.1.1.1 2000/05/17 11:08:36 idiscovery Exp $

This document describes the operating system independent file handling
capability in Tix.

1. The problem:

   (A) Handling user inputs. In various Tix widgets, the user may enter
   a text string to refer to a file, a directory or a file pattern.

   File:
	tixFileEntry
	tixFileSelectBox, the Selection part

   Directory:
	tixDirBox
	tixExFileSelectBox, the "Directory" part

   Pattern:
	tixFileSelectBox, the "Pattern" part
	tixExFileSelectBox, the "File" part

   (B) Interfacing with application

   These widgets support a -directory option

	tixDirList
	tixDirTree
	tixFileSelectBox
	tixExFileSelectBox

   These widgets support a -pattern option
	tixFileSelectBox
	tixExFileSelectBox

   (C) Displaying the file system in a single hierarchy

	tixDirList
	tixDirTree

2. Issues:

   (A) Unix:
	Tilde expansion

   (B) Windows:
	No single file system  hierarchy.

   (C) Both:
	Need to translate relative pathnames, "." and ".."
 
3. Reusuability:

   Many widgets need to list directory, glob, display hierarchy. We
   don't want to rewrite the same code again and again.


4. API.

   (A) Types of API

   External interface: Takes an input from the user or from the
   application and translate it to a canonical form.

   Internal interface: operate on filenames that are in canonical
   forms. There are run-time checking whether the filenames arein
   canonical forms.

   We have the two types of interfaces so that we don't need to
   perform needless translations from "user form" to "canonical
   form".


   (B) API Consistency

   External API always takes a filename in the native format and
   return file names in the native format.


   (C) Errors

   User errors are reported in an error dialog. Application errors
   triggers a TCL error return code.

   There should be in-line comments stating whether an input is from
   user or application.

5. VPATH: virtual hierarchical path

   Unix:

     In Unix, a VPATH is the same as a file pathname.

   Windows:

     In Windows 3.1, a VPATH is "xx\" followed by a normalized DOS
     file pathname. "xx" by itself is "My computer" and refers to the
     root directory of the C: drive.

     In Windows 95, a VPATH is "xx\xx\" followed by a normalized DOS
     file pathname. "xx" by itself is "Desktop" and refers to
     "C:\Windows\Desktop". "xx\xx" by itself is "My computer" and
     refers to the root directory of the C: drive.

     Normalization do not go into the virtual prefix. E.g.: the VPATH for
     "C:\Windows\..\..\" is "xx\xx\C:", not "xx\xx".


6. Normalization:

   tixFSNorm context text defFile flagsVar errorMsgVar

	This is the main function that translate a user input to
	normalized (canonical) form.

   Parameters:
        context:VPATH
	    The "current directory" under which the translation
	    occurs. It is used only if text refers to a relative
	    pathname.

	    if context is the empty string, then text must refer to an
	    absolute path.

	text:string
	    The (user/application) input that needs to be
	    normalized. The exact mode of translation depends on the
	    flags

	defFile:string
	    If the input is a directory, append this to the directory.

	flagsVar: ref to array
	    flag(noPattern): we don't want patterns. Treat all wild
	    card characters as normal file names

   Return value:
	No error occurs: errorMsg is not set and a list of three
	elements is returned:

	index 0: the normalized path of the input
	index 1: the VPATH of the directory.
	index 2: file(s) in the directory.
	index 3: pattern(s) in the directory.

	Either index 1 or 2, or both, are empty strings. They cannot
	be both non-empty.

   A Normalized path:

   1) is absolute
   2) has no double slashes
   3) has no trailing slashes
   4) has no relative pathnames
   5) has no tildes


   tixFSNormDir directory

	This is mainly used to check the validity of -directory option
	of the widgets.

   Parameter:
	directory:
	    Must be an existing absolute path.

   Return value:
	Returns normalized path. Error given when directory is not an
	existing absolute path


7. VPATH translation:

   tixFSVPath pathname:		returns the VPATH of pathname
   tixFSPath VPATH:		returns the pathname of VPATH


8. Valid file names:

   Should prompt to user about invalid filenames (E.g. In Windows,
   names cannot contain "*")

9. Creation prompt:

   If user enters a file or directory that doesn't exist, promt to ask
   whether he wants to create it.


10.