Provided by: libmotif-dev_2.3.3-5ubuntu1_amd64 bug

NAME

       XmFileSelectionBox — The FileSelectionBox widget class

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).

       ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
Binary file (standard input) matches