File open. A file open (fopn) widget is a comb-widget that consists of Label, pdl, slis, and Buttons. It is used to create GUI for file open dialogs. Sub-widgets of a fopn are used for entering the file path, patterns, and disks (in Windows). Two slis sub-widgets are used to host two layers of file lists. One file list contains sub-directories and files in a parent directory and the other list the sub-directories and files in a child directory. Pattern match for multiple sub-directories is implemented. All the sub-widgets are packed with grid, and can be easily repacked again in case the layout of a fopn widget is to be changed. 

EXAMPLE: The following example creates an fopn widget and then initializes it with a pattern "*" and a current directory. 

catch "destroy .fopn"
toplevel .fopn
set fopn [fopn.create .fopn.m]
fopn.insItems $fopn end \
    "{{All files} *} {{Tcl scripts} *.tcl} {Text *.txt}" -ptrn 
fopn.setDir $fopn [pwd] *
pack $fopn -expand 1 -fill both 

CLASS NAME: fopn

COMB-WIDGET OPTIONS

-path options It specifies options of a pull-down list (pdl) that contains an entry and a pull-down listbox. The entry is used for accepting both file names and patterns to be used in file searching. The pull-down listbox can be initialized with multiple items during the widget creation. A "-path {-items itemList}" initializes a list of the items in the pull-down list. Each element in this pull-down list should be a file name that can be used to facilitate the file selection. A <Return> in the entry completes a selection. If the selection is a file pattern, it starts a new file searching. 

-ptrn options It specifies options of a pull-down list (pdl) that contains an entry and a pull-down listbox. The entry is used for accepting a pattern that can be used for file searching. The pull-down listbox can be initialized with multiple items during the widget creation. A "-ptrn {-items itemList}" initializes a list of the items in the pull-down list. Each element in this pull-down list should be a two-item list. The first item is a brief comment of the file pattern, and the second item is the pattern. For example, {All files} {* *.*} provides a comment and pattern for all the files. When an item is selected, only the second element will be used as a pattern for searching. A <Return> in the entry starts a new file searching with the pattern selected. 

-disk options It specifies a pull-down list (pdl) for a disk drive selection. It is created only for Windows platforms. 

-listc options It specifes a listbox with scrollbars (slis). Both horizontal and vertical scrollbars can be configured. This sub-widget is used to select and browse the files and sub-directories in a child layer. A single clicking of an item selects it into the entry of the path. A double clicking completes a selection. If a directory is selected, it starts a new searching in the selected directory and its parent directory. Both list boxes may be updated. The searching results of the selected directory will be displayed in this listbox. 

-listp options It specifies a listbox with scrollbars (slis). Both horizontal and vertical scrollbars can be configured. This sub-widget is used to select and browse the files and sub-directories in a parent layer. A single clicking of an item selects in the entry of the path. A double clicking completes a selection. If a directory is selected, it starts a new searching in the selected directory and its parent directory. The searching results in the parent directory are displayed in this list box. 

-btn0, -btn1 These refer to sub-widgets of Button for Ok and Cancel of selections. The -btn0 refers to Ok and the -btn1 refers to Cancel. A global variable _comb($w,status) is used to record the status of a button press. A status value Ok indicates the button Ok was pressed, and a status value Cancel indicates the button Cancel was pressed. Whenever the Ok button is pressed, it starts a new searching if a file pattern is in the path. 

-pwdn, -pwdv, -dirn -dirv These refer to sub-widgets of Label. The labels referred to by -pwdn and -pwdv are used to display the present working directory when the fopn widget is created. The -pwdn is used for the name (e.g. PWD) and the -pwdv is used for the value (e.g. /usr/data/image). The labels referred to by -dirn and -dirv are used to display the directory name of the child layer. The -dirn is used for the name (e.g. DIR) and the -dirv is used for the value which is updated whenever a new directory is searched. 

fopn.bind pathname event scripts varList. This command binds the event of the sub-widget referred to by the varList to the scripts. The pathname must refer to a fopn widget. If the event is not specified, the current event that was bound to the sub-widget is returned. If the scripts is not specified, the current scripts bound to the event is returned. The scripts may be appended to the current ones if "+scripts" is specified instead of "scripts". If the varList is not specified, the command bind pathname event scripts is invoked. 

fopn.cget pathname -varName. This command retrieves the value of the -varName of a fopn widget. The pathname must refer to a fopn widget. The available -varNames are: -path, -ptrn, -pwdn, -<pwdv, -dirn, -dirv, -disk, -listp, -listc, -btn0, and -btn1. 

fopn.config pathname ?options?. This command configures options of an fopn widget referred to by the pathname. If the ?options? is not specified, a list of the fopn widget configuration is returned. Each element of the list is a list that provides information of a configurable option. The first element of a configurable option list is always the -varName. The rest of the contents depend on what the -varName refers to. If the -varName refers to a regular variable, the second element that is also the last element is the value for that variable. If the -varName refers to a sub-widget, the second element is the pathname of the sub-widget, the third is the class name, and the fourth that is also the last is the options used in previous widget creation or configuration. Since fopn is a multi-layer comb-widget, the value of an option may have multiple layers. For example: fopn.config .of -path {-ent {-background white}} -pwdn {-foreground red} configures an fopn widget referred to by .of. It sets the background color of the entry to white, and the foreground color of the label PWD to red. 

fopn.create pathname ?opitons?. This command creates an fopn widget with the given options. If the fopn widget is successfully created, the pathname is returned. Otherwise, an empty string is returned. The available options for an fopn.create command are: -path, -ptrn, -pwdn, -pwdv, -dirn, -dirv, -disk, -listp, -listc, -btn0, and -btn1. 

fopn.getEntry pathname -varName. This command retrieves the content of an entry of a sub-widget referred to by the -varName. The available -varNames are: -path, -ptrn, and -disk. 

fopn.getList pathname first last -varName. This command retrieves the items of a listbox referred to by the -varName. The first and last are start and end indices of the retrieved items. The available -varNames are: -path, -ptrn, -disk, -listp and -listc. 

fopn.insItems pathname items pos -varName. This command inserts a list of items into a listbox of a sub-widget referred to by the -varName at the position pos. The available -varNames are: -path, -ptrn, -disk, -listp and -listc. 

fopn.setEntry pathname string -varName. This command sets a string into an entry of a sub-widget referred to by the -varName. The available -varNames< are: -path, -ptrn, and -disk. 

fopn.setDir pathname dir pattern. This command initializes an fopn widget referred to by the pathname. The dir is a name of the directory where the files are to be searched; and the pattern is a list of tokens used to match a group of files whose names satisfy the matching rules of the Tcl build-in command glob. 

RELATED PROCEDURES

The followings are procedures used in an fopn widget implementation and test. A user may access to these procedures through the fopn widget API, and should never use these procedures directly in an application program. 

fopn.free pathname.
fopn.fillList listBox pattern dir select.
fopn.getFiles pathname.
fopn.getFullPath pathname.
fopn.parseSelect dir name. 
fopn.Ok pathname.
fopn.Cancel pathname.
fopn.selList pathname id x y.
fopn.selPattern pathname x y.
fopn.updateDisk pathname.
fopn.updatePattern pathname.