Subversion Repositories or1k_old

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.