Provided by: libmotif-dev_2.3.4-5ubuntu0.1_amd64 bug

NAME

       XmFileSelectionBox — The FileSelectionBox widget class "XmFileSelectionBox" "widget class"
       "FileSelectionBox"

SYNOPSIS

       #include <Xm/FileSB.h>

DESCRIPTION

       FileSelectionBox traverses through directories, views  the  files  and  subdirectories  in
       them, and then selects files.

       A FileSelectionBox has five main areas:

          •  A  text  input  field for displaying and editing a directory mask used to select the
             files to be displayed

          •  An optional text input field for displaying and editing a filter mask used to select
             the files to be displayed.

          •  A scrollable list of filenames

          •  A scrollable list of subdirectories

          •  A text input field for displaying and editing a filename

          •  A  group of PushButtons, labeled OK, Filter, Cancel, and Help.  The layout direction
             of the buttons depends on the XmNlayoutDirection resource.

       ####Additional  children  may  be  added   to   the   FileSelectionBox   after   creation.
       FileSelectionBox  inherits  the  layout  functionality  provided  by  SelectionBox for any
       additional children.  To remove the list of filenames, the list of subdirectories, or both
       from  the  FileSelectionBox  after  creation,  unmanage  the appropriate widgets and their
       labels.   The  list  and  label   widgets   are   obtained   through   a   call   to   the
       XmFileSelectionBoxGetChild  function.   To  remove  either  the directory list or the file
       list, unmanage the parent of the appropriate list widget and  unmanage  the  corresponding
       label.

       The  user  can  specify resources in a resource file for the automatically created widgets
       and gadgets of FileSelectionBox. The following list identifies the names of these  widgets
       (or gadgets) and the associated FileSelectionBox areas:

       FilterLabel
                 FilterText

       Filter Text
                 TextField

       Directory List
                 DirList

       Directory List Label
                 Dir

       DirL      Label

       DirText   TextField

       The  directory  mask is a string specifying the base directory to be examined and a search
       pattern.   Ordinarily,  the  directory  list  displays  the  subdirectories  of  the  base
       directory,  as  well as the base directory itself and its parent directory.  The file list
       ordinarily displays all files and/or subdirectories in the base directory that  match  the
       search pattern.

       Optionally,  the  search  pattern  mask  and  the  base  directory can be displayed in two
       separate text fields. This option is controlled by the XmNpathMode  resource.  Using  this
       alternate  display  does  not  change the meaning of resources that control the content of
       these fields: XmNdirectory, XmNdirMask, XmNpattern.

       A procedure specified by the XmNqualifySearchDataProc resource extracts the base directory
       and  search pattern from the directory mask.  If the directory specification is empty, the
       current working directory is used.  If the search pattern is empty, a pattern that matches
       all files is used.

       An  application  can supply its own XmNqualifySearchDataProc as well as its own procedures
       to search for subdirectories and files.  The  default  XmNqualifySearchDataProc  works  as
       follows:  The  directory  mask  is  a  pathname  that  can  contain  zero or more wildcard
       characters in its directory portion, its file portion, or both.  The directory  components
       of  the  directory  mask  —  up to, but not including, the first component with a wildcard
       character — specify the  directory  to  be  searched,  relative  to  the  current  working
       directory.  The remaining components specify the search pattern.  If the directory mask is
       empty or if its first  component  contains  a  wildcard  character,  the  current  working
       directory  is  searched.   If  no  component  of  the  directory  mask contains a wildcard
       character, the entire directory mask is the directory specification, and all files in that
       directory are matched.

       The  user  can  select  a  new  directory  to  examine  by  scrolling  through the list of
       directories and selecting  the  desired  directory  or  by  editing  the  directory  mask.
       Selecting  a  new directory from the directory list does not change the search pattern.  A
       user can select a  new  search  pattern  by  editing  the  directory  mask  or,  when  the
       FileSelectionBox  has  the  optional  XmNpathMode XmPATH_MODE_RELATIVE display, the filter
       text field.  Double clicking or pressing KActivate on a directory in  the  directory  list
       initiates  a  search  for files and subdirectories in the new directory, using the current
       search pattern.

       The user can select a file by scrolling through the list of filenames  and  selecting  the
       desired  file  or  by entering the filename directly into the text edit area.  Selecting a
       file from the list causes that filename to appear in the file selection text edit area.

       The user may select a new file as many times as desired.  The application is not  notified
       until the user takes one of the following actions:

          •  Selects the OK PushButton

          •  Presses KActivate while the selection text edit area has the keyboard focus

          •  Double clicks or presses KActivate on an item in the file list

       FileSelectionBox initiates a directory and file search when any of the following occurs:

          •  The FileSelectionBox is initialized

          •  The  function XtSetValues is used to change XmNdirMask, XmNdirectory, XmNpattern, or
             XmNfileTypeMask

          •  The user activates the Filter PushButton

          •  The user double clicks or presses KActivate on an item in the directory list

          •  The application calls XmFileSelectionDoSearch

          •  The user presses KActivate while the directory mask text edit area has the  keyboard
             focus

       When a file search is initiated, the FileSelectionBox takes the following actions:

          •  Constructs an XmFileSelectionBoxCallbackStruct structure with values appropriate for
             the action that initiated the search

          •  Calls the XmNqualifySearchDataProc with the callback structure  as  the  data  input
             argument

          •  Sets XmNdirectoryValid and XmNlistUpdated to False

          •  Calls   the   XmNdirSearchProc   with   the   qualified   data   returned   by   the
             XmNqualifySearchDataProc

       If XmNdirectoryValid is True, the FileSelectionBox takes the following additional actions:

          •  Sets XmNlistUpdated to False

          •  Calls  the   XmNfileSearchProc   with   the   qualified   data   returned   by   the
             XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)

          •  If  XmNlistUpdated is True and the file list is empty, displays the XmNnoMatchString
             in the file list and clears the selection text and XmNdirSpec

          •  If XmNlistUpdated is True and the file list is not empty, sets  the  selection  text
             and  XmNdirSpec  to  the qualified dir returned by the XmNqualifySearchDataProc (and
             possibly modified by the XmNdirSearchProc)

          •  Sets the directory mask text and XmNdirMask to the qualified mask  returned  by  the
             XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)

          •  Sets XmNdirectory to the qualified dir returned by the XmNqualifySearchDataProc (and
             possibly modified by the XmNdirSearchProc)

          •  Sets XmNpattern to the qualified pattern returned  by  the  XmNqualifySearchDataProc
             (and possibly modified by the XmNdirSearchProc)

       FileSelectionBox uses the XmQTactivatable trait.

   Data Transfer Behavior
       Child  widgets  of  a  FileSelectionBox  support  the data transfer operations and targets
       associated with their widget classes.

       In  addition,  if  the  source  of  a  data  transfer  is  the  directory  list   and   if
       XmNdirSearchProc has its default value, the directory list supports the FILE and FILE_NAME
       targets.

       If the source of a data transfer is the file list and if XmNfileSearchProc has its default
       value, the file list supports the FILE and FILE_NAME targets.

       In  either  case, FileSelectionBox adds an XmNconvertCallback procedure to the appropriate
       list.  This procedure adds FILE and FILE_NAME to the TARGETS returned  by  the  list.   It
       treats  requests for conversion of a selection to FILE and FILE_NAME exactly like requests
       for conversion to TEXT.

       If an application changes XmNdirSearchProc or XmNfileSearchProc and wants to  support  the
       FILE  and  FILE_NAME  targets on the corresponding list, it must provide support itself by
       adding a procedure to the list's XmNconvertCallback list.

   Descendants
       FileSelectionBox automatically creates the descendants shown in the following  table.   An
       application  can use XtNameToWidget to gain access to the named descendant. In addition, a
       user or an application can use the named descendant when specifying resource values.

       ┌─────────────────┬───────────────────────┬────────────────────────────────────┐
       │Named DescendantClassIdentity                           │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │ApplyXmPushButtonGadget    │ Apply button                       │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │CancelXmPushButtonGadget    │ Cancel button                      │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │DirXmLabelGadget         │ title above list of directories    │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │DirListXmList                │ list of directories                │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │DirListSWXmScrolledWindow      │ ScrolledWindow parent of DirList   │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │FilterLabelXmLabelGadget         │ title above filter box             │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │FilterTextXmText or XmTextField │ text within filter box             │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │HelpXmPushButtonGadget    │ Help button                        │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │ItemsXmLabelGadget         │ title above list of filenames      │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │ItemsListXmList                │ list of filenames                  │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │ItemsListSWXmScrolledWindow      │ ScrolledWindow parent of ItemsList │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │OKXmPushButtonGadget    │ OK button                          │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │SelectionXmLabelGadget         │ title above selection box          │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │SeparatorXmSeparatorGadget     │ optional dividing line             │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       │TextXmText or XmTextField │ text within selection box          │
       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
       └─────────────────┴───────────────────────┴────────────────────────────────────┘
   Classes
       FileSelectionBox  inherits  behavior,  resources,  and  traits   from   Core,   Composite,
       Constraint, XmManager, XmBulletinBoard, and XmSelectionBox.

       The class pointer is xmFileSelectionBoxWidgetClass.

       The class name is XmFileSelectionBox.

   New Resources
       The  following  table  defines a set of widget resources used by the programmer to specify
       data. The programmer can also set the resource values for the  inherited  classes  to  set
       attributes  for  this  widget. To reference a resource by name or by class in a .Xdefaults
       file, remove the XmN or XmC prefix and use the remaining letters. To specify  one  of  the
       defined  values  for  a  resource  in  a .Xdefaults file, remove the Xm prefix and use the
       remaining letters (in either lowercase or uppercase, but include any  underscores  between
       words).   The  codes  in  the  access  column indicate if the given resource can be set at
       creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
       not applicable (N/A).

       ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
--

RELATED

       Composite(3),  Constraint(3),  Core(3),  XmBulletinBoard(3),  XmCreateFileSelectionBox(3),
       XmCreateFileSelectionDialog(3), XmFileSelectionBoxGetChild(3), XmFileSelectionDoSearch(3),
       XmManager(3),         XmSelectionBox(3)         XmVaCreateFileSelectionBox(3),         and
       XmVaCreateManagedFileSelectionBox(3),.

                                                                            XmFileSelectionBox(3)