tix/man/EFileBox.n

   1 '\"
   2 '\" Copyright (c) 1996, Expert Interface Technologies
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" The file man.macros and some of the macros used by this file are
   8 '\" copyrighted: (c) 1990 The Regents of the University of California.
   9 '\"              (c) 1994-1995 Sun Microsystems, Inc.
  10 '\" The license terms of the Tcl/Tk distrobution are in the file
  11 '\" license.tcl.
  12 .so man.macros
  13 '----------------------------------------------------------------------
  14 .HS tixExFileSelectBox tix 4.0
  15 .BS
  16 '
  17 '
  18 '----------------------------------------------------------------------
  19 .SH NAME
  20 tixExFileSelectBox \- Create and manipulate tixExFileSelectBox widgets
  21 '
  22 '
  23 '
  24 '----------------------------------------------------------------------
  25 .SH SYNOPSIS
  26 \fBtixExFileSelectBox\fI \fIpathName ?\fIoptions\fR?
  27 '
  28 '
  29 '----------------------------------------------------------------------
  30 .PP
  31 .SH SUPER-CLASS
  32 The \fBTixExFileSelectBox\fR class does not have a super-class.
  33 '
  34 '----------------------------------------------------------------------
  35 .SH "STANDARD OPTIONS"
  36 '
  37 \fBTixExFileSelectBox\fR supports all the standard options of a frame
  38 widget. See the \fBoptions(n)\fR manual entry for details on the
  39 standard options.
  40 '
  41 '
  42 '----------------------------------------------------------------------
  43 .SH "WIDGET-SPECIFIC OPTIONS"
  44 '
  45 '----------BEGIN
  46 .LP
  47 .nf
  48 Name:           \fBbrowseCmd\fR
  49 Class:          \fBBrowseCmd\fR
  50 Switch:         \fB\-browsecmd\fR
  51 .fi
  52 .IP
  53 Specifies a command to call whenever the user browses on a filename in
  54 the file listbox (usually by single-clicking on the filename). The command
  55 is called with one argument, the complete pathname of the file.
  56 '----------END
  57 '
  58 '
  59 '----------BEGIN
  60 .LP
  61 .nf
  62 Name:           \fBcommand\fR
  63 Class:          \fBCommand\fR
  64 Switch:         \fB\-command\fR
  65 .fi
  66 .IP
  67 Specifies the command to be called when the user chooses on a filename
  68 the file listbox (usually by double-clicking on the filename). The command
  69 is called with one argument, the complete pathname of the file.
  70 '----------END
  71 '
  72 '----------BEGIN
  73 .LP
  74 .nf
  75 Name:           \fBdialog\fR
  76 Class:          \fBDialog\fR
  77 Switch:         \fB\-dialog\fR
  78 .fi
  79 .IP
  80 Specifies a dialog box which contains this ExFileSelectBox widget. The
  81 dialog box must be a widget of the class TixShell or its
  82 descendant classes. \fIThis is an internal option and should not be used
  83 by application programmers.\fR
  84 '----------END
  85 '----------BEGIN
  86 .LP
  87 .nf
  88 Name:           \fBdircmd\fR
  89 Class:          \fBDirCmd\fR
  90 Switch:         \fB\-dircmd\fR
  91 .fi
  92 .IP
  93 Specifies the TCL command to be called when a file listing is needed
  94 for a particular directory. If this option is not specified, by
  95 default the ExFileSelectBox widget will attempt to read the directory
  96 as a Unix directory. On special occasions, the application programmer
  97 may want to supply a special method for reading directories: for
  98 example, when he needs to list remote files. In this case, the
  99 \fB\-dircmd\fR option can be used. The specified command accepts three
 100 arguments: the first is the name of the directory to be listed; the
 101 second is a list of file patterns, the third is a Boolean value
 102 indicating whether hidden files should be listed. This command returns
 103 a list of names of the files of this directory which match with the
 104 file patterns.
 105 '----------END
 106 '
 107 '----------BEGIN
 108 .LP
 109 .nf
 110 Name:           \fBdirectory\fR
 111 Class:          \fBDirectory\fR
 112 Switch:         \fB\-directory\fR
 113 Alias:          \fB\-dir\fR
 114 .fi
 115 .IP
 116 Specifies the current directory whose files and sub-directories are
 117 displayed in the ExFileSelectBox.
 118 '----------END
 119 '
 120 '----------BEGIN
 121 .LP
 122 .nf
 123 Name:           \fBdisableCallback\fR
 124 Class:          \fBDisableCallback\fR
 125 Switch:         \fB\-disablecallback\fR
 126 .fi
 127 .IP
 128 A boolean value indicating whether callbacks should be disabled. When
 129 set to true, the TCL command specified by the \fB\-command\fR option
 130 is not executed when the \fB\-value\fR of the ExFileSelectBox
 131 widget changes.
 132 '----------END
 133 '
 134 '----------BEGIN
 135 '
 136 .LP
 137 .nf
 138 Name:           \fBfileTypes\fR
 139 Class:          \fBFileTypes\fR
 140 Switch:         \fB\-filetypes\fR
 141 .fi
 142 .IP
 143 Specifies the file types that can be selected from the "List Files of
 144 Type:" ComboBox subwidget. The value of this option must be a TCL
 145 list; each item of this list must in turn be a list of two elements.
 146 The first element is a list of file patterns. The second element is a
 147 string that describe these file patterns. For example:
 148 .nf
 149     tixExFileSelectBox .box -filetypes  {
 150         {{*}    {All files}}
 151         {{*.txt}        {Text files}}
 152         {{*.c *.h}      {C source files}}
 153     }
 154 .fi
 155 '----------END
 156 '
 157 '----------BEGIN
 158 '
 159 .LP
 160 .nf
 161 Name:           \fBshowHidden\fR
 162 Class:          \fBShowHidden\fR
 163 Switch:         \fB\-showhidden\fR
 164 .fi
 165 .IP
 166 Specifies whether hidden directories should be shown. By default, a
 167 directory name starting with a period "\." is considered as a hidden
 168 directory.
 169 '----------END
 170 '
 171 '----------BEGIN
 172 '
 173 .LP
 174 .nf
 175 Name:           \fBpattern\fR
 176 Class:          \fBPattern\fR
 177 Switch:         \fB\-pattern\fR
 178 .fi
 179 .IP
 180 Specifies whether the file pattern(s) to match with the files in the
 181 current directory. One or more file patterns can be given at the same
 182 time. For example, {*\.c *\.h} will match all files that have either the
 183 ".h" or ".c" extensions.
 184 '----------END
 185 '
 186 '
 187 '----------END
 188 '
 189 .LP
 190 .nf
 191 Name:           \fBvalue\fR
 192 Class:          \fBValue\fR
 193 Switch:         \fB\-value\fR
 194 Alias:          \fB\-selection\fR
 195 .fi
 196 .IP
 197 Specifies the name of the filename currently selected by the user.
 198 '----------END
 199 '
 200 '----------------------------------------------------------------------
 201 .SH SUBWIDGETS
 202 '----------BEGIN
 203 .LP
 204 .nf
 205 Name:           \fBcancel\fR
 206 Class:          \fBButton\fR
 207 .fi
 208 .IP
 209 The button widget with the "Cancel" label.
 210 '----------END
 211 '
 212 '----------BEGIN
 213 .LP
 214 .nf
 215 Name:           \fBdir\fR
 216 Class:          \fBTixComboBox\fR
 217 .fi
 218 .IP
 219 The ComboBox subwidget under the "Directories" heading.
 220 '----------END
 221 '----------BEGIN
 222 .LP
 223 .nf
 224 Name:           \fBdirlist\fR
 225 Class:          \fBTixDirList\fR
 226 .fi
 227 .IP
 228 The DirList subwidget that shows the hierarchical list of directories.
 229 '----------END
 230 '----------BEGIN
 231 .LP
 232 .nf
 233 Name:           \fBfile\fR
 234 Class:          \fBTixComboBox\fR
 235 .fi
 236 .IP
 237 The ComboBox subwidget under the "Files" heading.
 238 '----------END
 239 '
 240 '----------BEGIN
 241 .LP
 242 .nf
 243 Name:           \fBfilelist\fR
 244 Class:          \fBTixScrolledListBox\fR
 245 .fi
 246 .IP
 247 The ScrolledListBox subwidget that shows the list of filenames.
 248 '----------END
 249 '----------BEGIN
 250 .LP
 251 .nf
 252 Name:           \fBhidden\fR
 253 Class:          \fBCheckbutton\fR
 254 .fi
 255 .IP
 256 The checkbutton widget with the "Show Hidden Files" label.
 257 '----------END
 258 '
 259 '----------BEGIN
 260 .LP
 261 .nf
 262 Name:           \fBok\fR
 263 Class:          \fBButton\fR
 264 .fi
 265 .IP
 266 The button widget with the "OK" label.
 267 '----------END
 268 '
 269 '
 270 '----------BEGIN
 271 .LP
 272 .nf
 273 Name:           \fBtypes\fR
 274 Class:          \fBTixComboBox\fR
 275 .fi
 276 .IP
 277 The ComboBox subwidget under the "List Files of Type" heading.
 278 '----------END
 279 .BE
 280 '
 281 '
 282 '----------------------------------------------------------------------
 283 .SH DESCRIPTION
 284 '
 285 .PP
 286 '
 287 The \fBtixExFileSelectBox\fR command creates a new window (given by
 288 the \fIpathName\fR argument) and makes it into a
 289 ExFileSelectBox widget. Additional options, described above,
 290 may be specified on the command line or in the option database to
 291 configure aspects of the ExFileSelectBox such as its cursor
 292 and relief.
 293
 294 The ExFileSelectBox widget is usually embedded in a
 295 tixExFileSelectDialog widget. It provides an convenient method for the
 296 user to select files. The style of the ExFileSelectBox widget is very
 297 similar to the standard file dialog in MS Windows 3.1.
 298 '
 299 '
 300 '----------------------------------------------------------------------
 301 .SH WIDGET COMMANDS
 302 .PP
 303 '
 304 The \fBtixExFileSelectBox\fR command creates a new Tcl command whose
 305 name is the same as the path name of the ExFileSelectBox's
 306 window. This command may be used to invoke various operations on the
 307 widget. It has the following general form:
 308 '
 309 .DS C
 310 '
 311 \fIpathName option \fR?\fIarg arg ...\fR?
 312 .PP
 313 .DE
 314 '
 315 \fIPathName\fR is the name of the command, which is the same as the
 316 ExFileSelectBox widget's path name. \fIOption\fR and the
 317 \fIarg\fRs determine the exact behavior of the command. The following
 318 commands are possible for ExFileSelectBox widgets:
 319 '
 320 .TP
 321 \fIpathName \fBcget\fR \fIoption\fR
 322 '
 323 Returns the current value of the configuration option given by
 324 \fIoption\fR. \fIOption\fR may have any of the values accepted by the
 325 \fBtixExFileSelectBox\fR command.
 326 '
 327 '
 328 .TP
 329 '
 330 \fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR?
 331 '
 332 Query or modify the configuration options of the widget.  If no
 333 \fIoption\fR is specified, returns a list describing all of the
 334 available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
 335 information on the format of this list).  If \fIoption\fR is specified
 336 with no \fIvalue\fR, then the command returns a list describing the
 337 one named option (this list will be identical to the corresponding
 338 sublist of the value returned if no \fIoption\fR is specified).  If
 339 one or more \fIoption\-value\fR pairs are specified, then the command
 340 modifies the given widget option(s) to have the given value(s); in
 341 this case the command returns an empty string.  \fIOption\fR may have
 342 any of the values accepted by the \fBtixExFileSelectBox\fR command.
 343 '
 344 '
 345 .TP
 346 \fIpathName \fBfilter\fR
 347 '
 348 Forces the ExFileSelectBox widget to re-filter all the filenames
 349 according to the \fB\-pattern\fR option.
 350 '
 351 .TP
 352 \fIpathName \fBinvoke\fR
 353 '
 354 Forces the ExFileSelectBox widget to perform actions as if the user
 355 has pressed the "OK" button.
 356 '
 357 .TP
 358 \fIpathName \fBsubwidget \fI name ?args?\fR
 359 '
 360 When no options are given, this command returns the pathname of the
 361 subwidget of the specified name.
 362
 363 When options are given, the widget command of the specified subwidget
 364 will be called with these options.
 365 '
 366 '
 367 '
 368 '----------------------------------------------------------------------
 369 '.SH BINDINGS
 370 '.PP
 371 '
 372 '
 373 '
 374 '----------------------------------------------------------------------
 375 .SH KEYWORDS
 376 Tix(n)