# iwidgets2.2.0 User Commands - fileselectionbox

##

## NAME

         fileselectionbox - Create and manipulate  a  file  selection
         box widget

## SYNOPSIS

         fileselectionbox pathName ?options?

## INHERITANCE

         itk::Widget <- Fileselectionbox

## STANDARD OPTIONS

         activeBackground               background      borderWidthcursor
         foreground      highlightColor highlightThicknessinsertBackground
         insertBorderWidth              insertOffTime   insertOnTimeinsertWidth
         relief          repeatDelay    repeatInterval  selectBackground
         selectBorderWidth              selectForeground

         See the "options" manual entry for details on  the  standard
         options.

## ASSOCIATED OPTIONS

         textBackground  textFont

         See the "entryfield" widget manual entry for details on  the
         above associated options.

         labelFont       labelMargin

         See the "labeledwidget" widget manual entry for  details  on
         the above associated options.

         activeRelief    elementBorderWidth             jumptroughColor

         See the "scrollbar" widget class manual entry for details on
         the above associated options.

         hscrollMode     sbWidth        scrollMargin    textBackground
         textFont        vscrollMode

         See the "scrolledlistbox" widget manual entry for details on
         the above associated options.

## WIDGET-SPECIFIC OPTIONS

         Name:           childSitePos
         Class:          Position
         Command-Line Switch:           -childsitepos

              Specifies the position of the child site in the  selec-
              tion box: n, s, e, or w.  The default is s.

         Name:           dblDirsCommand
         Class:          Command
         Command-Line Switch:           -dbldirscommand

              Specifies a Tcl command procedure which is called  when
              an  directory  list  item is double clicked.  Typically
              this occurs when mouse button 1 is double clicked  over
              a directory name.

         Name:           dblFilesCommand
         Class:          Command
         Command-Line Switch:           -dblfilescommand

              Specifies a Tcl command procedure which is called  when
              an  file  list  item is double clicked.  Typically this
              occurs when mouse button 1 is  double  clicked  over  a
              file name.

         Name:           directory
         Class:          Directory
         Command-Line Switch:           -directory

              Specifies the initial default directory.   The  default
              is the present working directory.

         Name:           dirsfraction
         Class:          DirsFraction
         Command-Line Switch:           -dirsfraction

              Specifies the fraction as a percentage of  the  overall
              width that the directory list takes up.

         Name:           dirSearchCommand
         Class:          Command
         Command-Line Switch:           -dirsearchcommand

              Specifies a Tcl command to be  executed  to  perform  a
              directory search.  The command will receive the current
              working directory and filter mask  as  arguments.   The
              command  should  return  a  list of files which will be
              placed into the directory list.

         Name:           dirsLabel
         Class:          Text
         Command-Line Switch:           -dirslabel

              Specifies the text of the label for the directory list.
              The default is "Directories".

         Name:           dirsLabelPos
         Class:          Position
         Command-Line Switch:           -dirslabelpos
              Specifies the position of the label along the  side  of
              the directory list: n, ne, e, se, s, sw, w, or nw.  The
              default is nw.

         Name:           dirsOn
         Class:          DirsOn
         Command-Line Switch:           -dirson

              Specifies whether or not to display the directory list.
              The  value  may be given in any of the forms acceptable
              to Tcl_GetBoolean.  The default is true.

         Name:           fileSearchCommand
         Class:          Command
         Command-Line Switch:           -filesearchcommand

              Specifies a Tcl command to be  executed  to  perform  a
              file  search.   The  command  will  receive the current
              working directory and filter mask  as  arguments.   The
              command  should  return  a  list of files which will be
              placed into the file list.

         Name:           filesLabel
         Class:          Text
         Command-Line Switch:           -fileslabel

              Specifies the text of the label  for  the  files  list.
              The default is "Files".

         Name:           filesLabelPos
         Class:          Position
         Command-Line Switch:           -fileslabelpos

              Specifies the position of the label along the  side  of
              the  files  list: : n, ne, e, se, s, sw, w, or nw.  The
              default is nw.

         Name:           filesOn
         Class:          FilesOn
         Command-Line Switch:           -fileson

              Specifies whether or not to  display  the  files  list.
              The  value  may be given in any of the forms acceptable
              to Tcl_GetBoolean.  The default is true.

         Name:           fileType
         Class:          FileType
         Command-Line Switch:           -filetype

              Specify the type of files which may appear in the  file
              list: regular, directory, or any.  The default is regu-
              lar.

         Name:           filterCommand
         Class:          Command
         Command-Line Switch:           -filtercommand

              Specifies a Tcl command to be executed upon hitting the
              Return key in the filter entry widget.

         Name:           filterFocusCommand
         Class:          Command
         Command-Line Switch:           -filterfocuscommand

              Specifies a Tcl command to be executed  upon  reception
              of focus by the filter.

         Name:           filterLabel
         Class:          Text
         Command-Line Switch:           -filterlabel

              Specifies the text of the label for  the  filter  entry
              field.  The default is "Filter".

         Name:           filterLabelPos
         Class:          Position
         Command-Line Switch:           -filterlabelpos

              Specifies the position of the label along the  side  of
              the filter: n, ne, e, se, s, sw, w, or nw.  The default
              is nw.

         Name:           filterOn
         Class:          FilterOn
         Command-Line Switch:           -filteron

              Specifies whether or not to display the  filter  entry.
              The  value  may be given in any of the forms acceptable
              to Tcl_GetBoolean.  The default is true.

         Name:           height
         Class:          Height
         Command-Line Switch:           -height

              Specifies the height of the selection box.   The  value
              may  be  specified  in  any  of the forms acceptable to
              Tk_GetPixels.  The default is 360 pixels.

         Name:           horizmargin
         Class:          Margin
         Command-Line Switch:           -horizmargin

              Specifies    distance    between    the    lists    and
              filter/selection  entries.   The  value may be given in
              any of  the  forms  acceptable  to  Tk_GetPixels.   The
              default is 7.

         Name:           invalid
         Class:          Command
         Command-Line Switch:           -invalid

              Command to be executed should the  filter  contents  be
              proven invalid.  The default is {bell}.

         Name:           mask
         Class:          Mask
         Command-Line Switch:           -mask

              Specifies the initial file mask string.  The default is
              "*".

         Name:           noMatchString
         Class:          NoMatchString
         Command-Line Switch:           -nomatchstring

              Specifies the string to be displayed in the files  list
              should  no  files  match  the  mask.  The default is "[
              ]".

         Name:           selectDirCommand
         Class:          Command
         Command-Line Switch:           -selectdirommand

              Specifies a Tcl command to be executed following selec-
              tion of a directory in the directory list.

         Name:           selectFileCommand
         Class:          Command
         Command-Line Switch:           -selectfileommand

              Specifies a Tcl command to be executed following selec-
              tion of a file in the files list.

         Name:           selectionCommand
         Class:          Command
         Command-Line Switch:           -selectioncommand

              Specifies a Tcl command to be executed upon hitting the
              Return key in the selection entry widget.

         Name:           selectionFocusCommand
         Class:          Command
         Command-Line Switch:           -selectionfocuscommand

              Specifies a Tcl command to be executed  upon  reception
              of focus by the selection entry.

         Name:           selectionImage
         Class:          Image
         Command-Line Switch:           -selectionimage

              Specifies a image to be used  as  the  selection  entry
              label.  The  image  may be any of the values created by
              the image create command.

         Name:           selectionLabel
         Class:          Text
         Command-Line Switch:           -selectionlabel

              Specifies the text of the label for the selection entry
              field.  The default is "Selection".

         Name:           selectionLabelPos
         Class:          Position
         Command-Line Switch:           -selectionlabelpos

              Specifies the position of the label along the  side  of
              the  selection:  n,  ne,  e,  se, s, sw, w, or nw.  The
              default is nw.

         Name:           selectionOn
         Class:          SelectionOn
         Command-Line Switch:           -selectionon

              Specifies whether  or  not  to  display  the  selection
              entry.   The  value  may  be  given in any of the forms
              acceptable to Tcl_GetBoolean.  The default is true.

         Name:           style
         Class:          Syle
         Command-Line Switch:           -style

              Specifies display style of the fileselectionbox:  motif
              or notif.  The default is motif which reflects the lay-
              out of the OSF/Motif standard Xmfileselectionbox widget
              composed  of  directory and file scrolled lists as well
              as filter and selection entry fields.  The notif option
              setting  varies  the layout by removing directory names
              from the files, separates the lists by a paned  window,
              and  changes  the  filter  and  entry  fields into com-
              boboxes.

         Name:           vertmargin
         Class:          Margin
         Command-Line Switch:           -vertmargin

              Specifies  distance  between  the  directory  and  file
              lists.   The  value  may  be  given in any of the forms
              acceptable to Tk_GetPixels.  The default  is  7.   This
              option  is  only useful for motif styled fileselection-
              boxes.  For notif styled  ones,  use  the  dirsfraction
              option  to  modify  spacing  between  the directory and
              files lists.

         Name:           width
         Class:          Width
         Command-Line Switch:           -width

              Specifies the width of the selection  box.   The  value
              may  be  specified  in  any  of the forms acceptable to
              Tk_GetPixels.  The default is 470 pixels.

##

## DESCRIPTION

         The fileselectionbox command creates a  file  selection  box
         similar  to the OSF/Motif standard Xmfileselectionbox compo-
         site widget.  The fileselectionbox is composed of  directory
         and  file  scrolled  lists  as  well as filter and selection
         entry fields.  Bindings are in place such that selection  of
         a  directory  list  item  loads  the  filter entry field and
         selection of a file list  item  loads  the  selection  entry
         field.   Options exist to control the appearance and actions
         of the widget.

## METHODS

         The fileselectionbox command creates a new Tcl command whose
         name  is pathName.  This command may be used to invoke vari-
         ous operations on the widget.  It has the following  general
         form:

              pathName option ?arg arg ...?

         Option and the args determine the exact behavior of the com-
         mand.   The  following  commands are possible for fileselec-
         tionbox widgets:

## WIDGET-SPECIFIC METHODS

         pathName cget option
              Returns the current value of the  configuration  option
              given  by  option.   Option  may have any of the values
              accepted by the fileselectionbox command.

         pathName childsite
              Returns the child site widget path name.

         pathName configure ?option? ?value option value ...?
              Query  or  modify  the  configuration  options  of  the
              widget.   If  no  option  is  specified, returns a list
              describing all of the available  options  for  pathName
              (see  Tk_ConfigureInfo for information on the format of
              this list).  If option is specified with no value, then
              the  command  returns  a  list describing the one named
              option (this list will be identical to the  correspond-
              ing  sublist  of  the  value  returned  if no option is
              specified).  If one or more  option - value  pairs  are
              specified,  then  the command modifies the given widget
              option(s) to have the given value(s);  in this case the
              command  returns  an empty string.  Option may have any
              of the values accepted by the fileselectionbox command.

         pathName filter
              Update the current contents of the file  selection  box
              based on the current filter entry field value.

         pathName get
              Returns  the  current  value  of  the  selection  entry
              widget.

## COMPONENTS

         Name:           childsite
         Class:          Frame

              The childsite component is the user child site for  the
              file  selection  box.   See  the  "frame" widget manual
              entry for details on the childsite component item.

         Name:           dirs
         Class:          Scrolledlistbox

              The dirs component is the directory list  box  for  the
              file  selection  box.  See the "scrolledlistbox" widget
              manual entry for details on the dirs component item.

         Name:           files
         Class:          Scrolledlistbox

              The files component is the file list box for  the  file
              selection box.  See the "scrolledlistbox" widget manual
              entry for details on the files component item.

         Name:           filter
         Class:          Entryfield

              The filter component is the entry field for user  input
              of  the  filter  value.   See  the  "entryfield" widget
              manual entry for details on the filter component item.

         Name:           selection
         Class:          Entryfield

              The selection component is the  entry  field  for  user
              input  of  the  currently selected file value.  See the
              "entryfield" widget manual entry  for  details  on  the
              selection component item.

## EXAMPLE

              option add *textBackground GhostWhite

              fileselectionbox .fsb
              pack .fsb -padx 10 -pady 10 -fill both -expand yes

## AUTHOR(S)

         Mark L. Ulferts

         Anthony Parent

## KEYWORDS

         fileselectionbox, widget