Provided by: libmotif-dev_2.3.8-2build1_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)