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