| 1 | |
| 2 | =head1 NAME |
| 3 | |
| 4 | Tk::FileSelect - a widget for choosing files |
| 5 | |
| 6 | =for pm Tk/FileSelect.pm |
| 7 | |
| 8 | =for category Popups and Dialogs |
| 9 | |
| 10 | =head1 SYNOPSIS |
| 11 | |
| 12 | use Tk::FileSelect; |
| 13 | |
| 14 | $FSref = $top->FileSelect(-directory => $start_dir); |
| 15 | $top - a window reference, e.g. MainWindow->new |
| 16 | $start_dir - the starting point for the FileSelect |
| 17 | $file = $FSref->Show; |
| 18 | Executes the fileselector until either a filename is |
| 19 | accepted or the user hits Cancel. Returns the filename |
| 20 | or the empty string, respectively, and unmaps the |
| 21 | FileSelect. |
| 22 | $FSref->configure(option => value[, ...]) |
| 23 | Please see the Populate subroutine as the configuration |
| 24 | list changes rapidly. |
| 25 | |
| 26 | =head1 DESCRIPTION |
| 27 | |
| 28 | This Module pops up a Fileselector box, with a directory entry on |
| 29 | top, a list of directories in the current directory, a list of |
| 30 | files in the current directory, an entry for entering/modifying a |
| 31 | file name, an accept button and a cancel button. |
| 32 | |
| 33 | You can enter a starting directory in the directory entry. After |
| 34 | hitting Return, the listboxes get updated. Double clicking on any |
| 35 | directory shows you the respective contents. Single clicking on a |
| 36 | file brings it into the file entry for further consideration, |
| 37 | double clocking on a file pops down the file selector and calls |
| 38 | the optional command with the complete path for the selected file. |
| 39 | Hitting return in the file selector box or pressing the accept |
| 40 | button will also work. *NOTE* the file selector box will only then |
| 41 | get destroyed if the file name is not zero length. If you want |
| 42 | yourself take care of it, change the if(length(.. in sub |
| 43 | accept_file. |
| 44 | |
| 45 | =head1 AUTHORS |
| 46 | |
| 47 | Based on original FileSelect by |
| 48 | Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich, |
| 49 | April 22, 1995 adapted by |
| 50 | Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas, |
| 51 | 21Jun95 |
| 52 | |
| 53 | =head1 HISTORY |
| 54 | |
| 55 | =head2 950621 -- The following changes were made: |
| 56 | |
| 57 | =over 4 |
| 58 | |
| 59 | =item * |
| 60 | |
| 61 | Rewrote Tk stuff to take advantage of new Compound widget module, so |
| 62 | FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2 |
| 63 | subwidgets. |
| 64 | |
| 65 | =item * |
| 66 | |
| 67 | Moved entry labels (from to the left of) to above the entry fields. |
| 68 | |
| 69 | =item * |
| 70 | |
| 71 | Caller is now able to control these aspects of widget, in both |
| 72 | FileSelect (new) and configure : |
| 73 | |
| 74 | (Please see subroutine Populate for details, as these options |
| 75 | change rapidly!) |
| 76 | |
| 77 | =item * |
| 78 | |
| 79 | I changed from Double-Button-1 to Button-1 in the Files listbox, |
| 80 | to work with multiple mode in addition to browse mode. I also |
| 81 | made some name changes (LastPath --> saved_path, ...). |
| 82 | |
| 83 | =item * |
| 84 | |
| 85 | The show method is not yet updated. |
| 86 | |
| 87 | =item * |
| 88 | |
| 89 | The topLevel stuff is not done yet. I took it out while I toy with |
| 90 | the idea of FileSelect as a subwidget. Then the 'normal' topLevel |
| 91 | thing with Buttons along the bottom could be build on top of it. |
| 92 | |
| 93 | =item * |
| 94 | |
| 95 | By request of Henry Katz <katz@fs09.webo.dg.com>, I added the functionality |
| 96 | of using the Directory entry as a filter. So, if you want to only see the |
| 97 | *.c files, you add a .c (the *'s already there :) and hit return. |
| 98 | |
| 99 | =back |
| 100 | |
| 101 | =head2 95/10/17, SOL, LUCC. lusol@Lehigh.EDU |
| 102 | |
| 103 | =over 4 |
| 104 | |
| 105 | =item * |
| 106 | |
| 107 | Allow either file or directory names to be accepted. |
| 108 | |
| 109 | =item * |
| 110 | |
| 111 | Require double click to move into a new directory rather than a single |
| 112 | click. This allows a single click to select a directory name so it can |
| 113 | be accepted. |
| 114 | |
| 115 | =item * |
| 116 | |
| 117 | Add -verify list option so that standard Perl file test operators (like |
| 118 | -d and -x) can be specified for further name validation. The default |
| 119 | value is the special value '!-d' (not a directory), so any name can be |
| 120 | selected as long as it's not a directory - after all, this IS FileSelect! |
| 121 | |
| 122 | For example: |
| 123 | |
| 124 | $fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]); |
| 125 | |
| 126 | ensures that the selected name is a directory. Further, if an element of |
| 127 | the list is an array reference, the first element is a code reference to a |
| 128 | subroutine and the remaining optional elements are it's parameters. The |
| 129 | subroutine is called like this: |
| 130 | |
| 131 | &verify_code($cd, $leaf, $P1, $P2, ... $Pn); |
| 132 | |
| 133 | where $cd is the current directory, $leaf is a directory or file name, and |
| 134 | $P1 .. $Pn are your optional parameters. The subroutine should return TRUE |
| 135 | if success or FALSE if failure. |
| 136 | |
| 137 | =back |
| 138 | |
| 139 | =head2 961008 -- derf@ti.com : |
| 140 | |
| 141 | By request of Jim Stern <js@world.northgrum.com> and Brad Vance |
| 142 | <bvance@ti.com>, I updated the Accept and Show functions to support |
| 143 | selection of multiple files. I also corrected a typo in the -verify code. |
| 144 | |
| 145 | =cut |
| 146 | |