


XmFileSelectionBox(3X)				       XmFileSelectionBox(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmFFiilleeSSeelleeccttiioonnBBooxx - The FileSelectionBox widget class

SYNOPSIS


  ##iinncclluuddee <<XXmm//FFiilleeSSBB..hh>>

DESCRIPTION
  FileSelectionBox traverses through directories, views	the files and sub-
  directories in them, and then	selects	files.

  A FileSelectionBox has five main areas:

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

    oo++  A scrollable list of filenames

    oo++  A scrollable list of subdirectories

    oo++  A text input field for displaying and editing a filename

    oo++  A group of PushButtons, labeled OOKK, FFiilltteerr, CCaanncceell, and HHeellpp

  Additional children may be added to the FileSelectionBox after creation.
  FileSelectionBox inherits the	layout functionality provided by SelectionBox
  for any additional children.	The list of filenames, the list	of subdirec-
  tories, or both can be removed from the FileSelectionBox after creation by
  unmanaging the appropriate widgets and their labels.	The list and label
  widgets are obtained by calling the function XXmmFFiilleeSSeelleeccttiioonnBBooxxGGeettCChhiilldd.
  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 iden-
  tifies the names of these widgets (or	gadgets) and the associated
  FileSelectionBox areas.

	  Filter Label-"FilterLabel"

	  Filter Text-"Text"

	  Directory List-"DirList"

	  Directory List Label-"Dir"

  The directory	mask is	a string specifying the	base directory to be examined
  and a	search pattern.	 Ordinarily, the directory list	displays the sub-
  directories 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.

  A procedure specified	by the XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc	resource extracts the
  base directory and search pattern from the directory mask.  If the direc-
  tory 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 XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc as	well as	its
  own procedures to search for subdirectories and files.  The default
  XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc works as follows: The directory mask	is a pathname
  that can contain zero	or more	_w_i_l_d_c_a_r_d 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 com-
  ponents 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 specifica-
  tion,	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	edit-
  ing the directory mask.  Double clicking or pressing KKAAccttiivvaattee on a direc-
  tory 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 these actions:

    oo++  Selects the OOKK PushButton.

    oo++  Presses KKAAccttiivvaattee while the selection text edit area has	the keyboard
       focus.

    oo++  Double clicks or	presses	KKAAccttiivvaattee on an	item in	the file list

  FileSelectionBox initiates a directory and file search when any of the fol-
  lowing occurs:

    oo++  The FileSelectionBox is initialized

    oo++  The function XXttSSeettVVaalluueess	is used	to change XXmmNNddiirrMMaasskk, XXmmNNddiirreeccttoorryy,
       XXmmNNppaatttteerrnn, or XXmmNNffiilleeTTyyppeeMMaasskk

    oo++  The user	activates the FFiilltteerr PushButton

    oo++  The user	double clicks or presses KKAAccttiivvaattee on an item in the direc-
       tory list

    oo++  The application calls XXmmFFiilleeSSeelleeccttiioonnDDooSSeeaarrcchh

    oo++  The user	presses	KKAAccttiivvaattee while	the directory mask text	edit area has
       the keyboard focus

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

    oo++  Constructs an XXmmFFiilleeSSeelleeccttiioonnBBooxxCCaallllbbaacckkSSttrruucctt structure	with values
       appropriate for the action that initiated the search

    oo++  Calls the XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc with the callback structure as the
       data input argument

    oo++  Sets XXmmNNddiirreeccttoorryyVVaalliidd and XXmmNNlliissttUUppddaatteedd to False

    oo++  Calls the XXmmNNddiirrSSeeaarrcchhPPrroocc with the qualified data returned by the
       XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc

  If XXmmNNddiirreeccttoorryyVVaalliidd is True,	the FileSelectionBox takes these additional
  actions:

    oo++  Sets XXmmNNlliissttUUppddaatteedd to False

    oo++  Calls the XXmmNNffiilleeSSeeaarrcchhPPrroocc with	the qualified data returned by the
       XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc	(and possibly modified by the XXmmNNddiirrSSeeaarr--
       cchhPPrroocc)

    oo++  If XXmmNNlliissttUUppddaatteedd is True and the file list is empty, displays the
       XXmmNNnnooMMaattcchhSSttrriinngg	in the file list and clears the	selection text and
       XXmmNNddiirrSSppeecc

    oo++  If XXmmNNlliissttUUppddaatteedd is True and the file list is not empty, sets the
       selection text and XXmmNNddiirrSSppeecc to	the qualified _d_i_r returned by the
       XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc	(and possibly modified by the XXmmNNddiirrSSeeaarr--
       cchhPPrroocc)

    oo++  Sets the	directory mask text and	XXmmNNddiirrMMaasskk to the qualified _m_a_s_k
       returned	by the XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc	(and possibly modified by the
       XXmmNNddiirrSSeeaarrcchhPPrroocc)

    oo++  Sets XXmmNNddiirreeccttoorryy to the	qualified _d_i_r returned by the XXmmNNqquuaalliiffyySSeeaarr--
       cchhDDaattaaPPrroocc (and possibly	modified by the	XXmmNNddiirrSSeeaarrcchhPPrroocc)

    oo++  Sets XXmmNNppaatttteerrnn to the qualified	_p_a_t_t_e_r_n	returned by the	XXmmNNqquuaall--
       iiffyySSeeaarrcchhDDaattaaPPrroocc (and possibly modified	by the XXmmNNddiirrSSeeaarrcchhPPrroocc)

  Classes

  FileSelectionBox inherits behavior and resources from	CCoorree, CCoommppoossiittee, CCoonn--
  ssttrraaiinntt, XXmmMMaannaaggeerr, XXmmBBuulllleettiinnBBooaarrdd, and XXmmSSeelleeccttiioonnBBooxx.

  The class pointer is xxmmFFiilleeSSeelleeccttiioonnBBooxxWWiiddggeettCCllaassss.

  The class name is XXmmFFiilleeSSeelleeccttiioonnBBooxx.

  New Resources

  The following	table defines a	set of widget resources	used by	the program-
  mer 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	XXmmNN or XXmmCC
  prefix and use the remaining letters.	 To specify one	of the defined values
  for a	resource in a .Xdefaults file, remove the XXmm prefix and	use the
  remaining letters (in	either lowercase or uppercase, but include any under-
  scores between words).  The codes in the access column indicate if the
  given	resource can be	set at creation	time (C), set by using XXttSSeettVVaalluueess
  (S), retrieved by using XXttGGeettVVaalluueess (G), or is not applicable	(N/A).

		       XXmmFFiilleeSSeelleeccttiioonnBBooxx RReessoouurrccee SSeett
	______________________________________________________________
	NNaammee				 DDeeffaauulltt		AAcccceessss
	      CCllaassss			       TTyyppee
	______________________________________________________________
	______________________________________________________________
	XmNdirectory			 dynamic		CSG
	      XmCDirectory			XmString
	______________________________________________________________
	XmNdirectoryValid		 dynamic		SG
	      XmCDirectoryValid			Boolean
	______________________________________________________________
	XmNdirListItems			 dynamic		SG
	      XmCDirListItems			XmStringTable
	______________________________________________________________
	XmNdirListItemCount		 dynamic		SG
	      XmCDirListItemCount		int
	______________________________________________________________
	XmNdirListLabelString		 dynamic		CSG
	      XmCDirListLabelString		XmString
	______________________________________________________________
	XmNdirMask			 dynamic		CSG
	      XmCDirMask			XmString
	______________________________________________________________
	XmNdirSearchProc		 default procedure	CSG
	      XmCDirSearchProc			XmSearchProc
	______________________________________________________________
	XmNdirSpec			 dynamic		CSG
	      XmCDirSpec			XmString
	______________________________________________________________
	XmNfileListItems		 dynamic		SG
	      XmCItems				XmStringTable
	______________________________________________________________
	XmNfileListItemCount		 dynamic		SG
	      XmCItemCount			int
	______________________________________________________________
	XmNfileListLabelString		 dynamic		CSG
	      XmCFileListLabelString		XmString
	______________________________________________________________
	XmNfileSearchProc		 default procedure	CSG
	      XmCFileSearchProc			XmSearchProc
	______________________________________________________________
	XmNfileTypeMask			 XmFILE_REGULAR		CSG
	      XmCFileTypeMask			unsigned char
	______________________________________________________________
	XmNfilterLabelString		 dynamic		CSG
	      XmCFilterLabelString		XmString
	______________________________________________________________
	XmNlistUpdated			 dynamic		SG
	      XmCListUpdated			Boolean
	______________________________________________________________
	XmNnoMatchString		 " [	] "		CSG
	      XmCNoMatchString			XmString
	______________________________________________________________
	XmNpattern			 dynamic		CSG
	      XmCPattern			XmString
	______________________________________________________________
	XmNqualifySearchDataProc	 default procedure	CSG
	      XmCQualifySearchDataProc		XmQualifyProc
	______________________________________________________________

  XXmmNNddiirreeccttoorryy
	    Specifies the base directory used in combination with XXmmNNppaatttteerrnn
	    in determining the files and directories to	be displayed.  The
	    default value is determined	by the XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc	and
	    depends on the initial values of XXmmNNddiirrMMaasskk, XXmmNNddiirreeccttoorryy, and
	    XXmmNNppaatttteerrnn.	 If the	default	is NULL	or empty, the current working
	    directory is used.

  XXmmNNddiirreeccttoorryyVVaalliidd
	    Specifies an attribute that	is set only by the directory search
	    procedure.	The value is set to True if the	directory passed to
	    the	directory search procedure can actually	be searched.  If this
	    value is False the file search procedure is	not called, and
	    XXmmNNddiirrMMaasskk,	XXmmNNddiirreeccttoorryy, and XXmmNNppaatttteerrnn are not changed.

  XXmmNNddiirrLLiissttIItteemmss
	    Specifies the items	in the directory list.	XXttGGeettVVaalluueess for	this
	    resource returns the list items themselves,	not a copy of the
	    list items.	 The application must not free the returned items.

  XXmmNNddiirrLLiissttIItteemmCCoouunntt
	    Specifies the number of items in the directory list.  The value
	    must not be	negative.

  XXmmNNddiirrLLiissttLLaabbeellSSttrriinngg
	    Specifies the label	string of the directory	list.  The default
	    for	this resource depends on the locale.  In the C locale the
	    default is "Directories".

  XXmmNNddiirrMMaasskk
	    Specifies the directory mask used in determining the files and
	    directories	to be displayed.  The default value is determined by
	    the	XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc and depends on	the initial values of
	    XXmmNNddiirrMMaasskk,	XXmmNNddiirreeccttoorryy, and XXmmNNppaatttteerrnn.

  XXmmNNddiirrSSeeaarrcchhPPrroocc
	    Specifies a	directory search procedure to replace the default
	    directory-search procedure.	 FileSelectionBox's default
	    directory-search procedure fulfills	the needs of most applica-
	    tions.  Because it is impossible to	cover the requirements of all
	    applications, you can replace the default search procedure.

	    The	directory search procedure is called with two arguments: the
	    FileSelectionBox widget and	a pointer to an	XXmmFFiilleeSSeelleeccttiioonnBBooxx--
	    CCaallllbbaacckkSSttrruucctt structure.  The callback structure is generated by
	    the	XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc and contains all information
	    required to	conduct	a directory search, including the directory
	    mask and a qualified base directory	and search pattern.  Once
	    called, it is up to	the search routine to generate a new list of
	    directories	and update the FileSelectionBox	widget by using
	    XXttSSeettVVaalluueess.

	    The	search procedure must set XXmmNNddiirreeccttoorryyVVaalliidd and	XXmmNNlliissttUUpp--
	    ddaatteedd.  If it generates a new list of directories, it must also
	    set	XXmmNNddiirrLLiissttIItteemmss	and XXmmNNddiirrLLiissttIItteemmCCoouunntt.

	    If the search procedure cannot search the specified	directory, it
	    must warn the user and set XXmmNNddiirreeccttoorryyVVaalliidd and XXmmNNlliissttUUppddaatteedd
	    to False, unless it	prompts	and subsequently obtains a valid
	    directory.	If the directory is valid but is the same as the
	    current XXmmNNddiirreeccttoorryy, the search procedure must set	XXmmNNddiirreeccttoo--
	    rryyVVaalliidd to True, but it may	elect not to generate a	new list of
	    directories.  In this case is must set XXmmNNlliissttUUppddaatteedd to False.

	    If the search procedure generates a	new list of directories, it
	    must set XXmmNNddiirrLLiissttIItteemmss to	the new	list of	directories and
	    XXmmNNddiirrLLiissttIItteemmCCoouunntt	to the number of items in the list.  If	there
	    are	no directories,	it sets	XXmmNNddiirrLLiissttIItteemmss	to NULL	and XXmmNNddiirr--
	    LLiissttIItteemmCCoouunntt to 0.	 In either case	it must	set XXmmNNddiirreeccttoorryyVVaalliidd
	    and	XXmmNNlliissttUUppddaatteedd to True.

	    The	search procedure ordinarily should not change the callback
	    struct.  But if the	original directory is not valid, the search
	    procedure may obtain a new directory from the user.	 In this case
	    it should set the _d_i_r member of the	callback struct	to the new
	    directory, call the	XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc with the callback
	    struct as the input	argument, and copy the qualified data
	    returned by	the XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc into the callback
	    struct.

  XXmmNNddiirrSSppeecc
	    Specifies the full file path specification.	 This is the XXmmNNtteexxtt--
	    SSttrriinngg resource in SelectionBox, renamed for FileSelectionBox.
	    The	default	value is determined by the FileSelectionBox after
	    conducting the initial directory and file search.

  XXmmNNffiilleeLLiissttIItteemmss
	    Specifies the items	in the file list.  This	is the XXmmNNlliissttIItteemmss
	    resource in	SelectionBox, renamed for FileSelectionBox.  XXttGGeett--
	    VVaalluueess for this resource returns the list items themselves,	not a
	    copy of the	list items.  The application must not free the
	    returned items.

  XXmmNNffiilleeLLiissttIItteemmCCoouunntt
	    Specifies the number of items in the file list.  This is the
	    XXmmNNlliissttIItteemmCCoouunntt resource in SelectionBox, renamed for FileSelec-
	    tionBox.  The value	must not be negative.

  XXmmNNffiilleeLLiissttLLaabbeellSSttrriinngg
	    Specifies the label	string of the file list.  This is the
	    XXmmNNlliissttLLaabbeellSSttrriinngg resource	in SelectionBox, renamed for
	    FileSelectionBox.  The default for this resource depends on	the
	    locale.  In	the C locale the default is "Files".

  XXmmNNffiilleeSSeeaarrcchhPPrroocc
	    Specifies a	file search procedure to replace the default file-
	    search procedure.  FileSelectionBox's default file-search pro-
	    cedure fulfills the	needs of most applications.  Because it	is
	    impossible to cover	the requirements of all	applications, you can
	    replace the	default	search procedure.

	    The	file search procedure is called	with two arguments: the
	    FileSelectionBox widget and	a pointer to an	XXmmFFiilleeSSeelleeccttiioonnBBooxx--
	    CCaallllbbaacckkSSttrruucctt structure.  The callback structure is generated by
	    the	XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc (and possibly modified	by the
	    XXmmNNddiirrSSeeaarrcchhPPrroocc).	It contains all	information required to	con-
	    duct a file	search,	including the directory	mask and a qualified
	    base directory and search pattern.	Once called, it	is up to the
	    search routine to generate a new list of files and update the
	    FileSelectionBox widget by using XXttSSeettVVaalluueess.

	    The	search procedure must set XXmmNNlliissttUUppddaatteedd.  If it generates a
	    new	list of	files, it must also set	XXmmNNffiilleeLLiissttIItteemmss and
	    XXmmNNffiilleeLLiissttIItteemmCCoouunntt.

	    The	search procedure is recommended	always to generate a new list
	    of files.  If the _m_a_s_k member of the callback struct is the	same
	    as the _m_a_s_k	member of the callback struct in the preceding call
	    to the search procedure, the procedure may elect not to generate
	    a new list of files.  In this case it must set XXmmNNlliissttUUppddaatteedd to
	    False.

	    If the search procedure generates a	new list of files, it must
	    set	XXmmNNffiilleeLLiissttIItteemmss to the	new list of files and XXmmNNffiilleeLLiiss--
	    ttIItteemmCCoouunntt to the number of	items in the list.  If there are no
	    files, it sets XXmmNNffiilleeLLiissttIItteemmss to NULL and	XXmmNNffiilleeLLiissttIItteemmCCoouunntt
	    to 0.  In either case it must set XXmmNNlliissttUUppddaatteedd to	True.

	    In constructing the	list of	files, the search procedure should
	    include only files of the types specified by the widget's
	    XXmmNNffiilleeTTyyppeeMMaasskk.

	    Setting XXmmNNddiirrSSppeecc is optional, but	recommended.  Set this
	    attribute to the full file specification of	the directory
	    searched.  The directory specification is displayed	below the
	    directory and file lists.

  XXmmNNffiilleeTTyyppeeMMaasskk
	    Specifies the type of files	listed in the file list.  Following
	    are	the possible values:

	      oo++
	      XXmmFFIILLEE__RREEGGUULLAARR restricts the file	list to	contain	only regular
	      files.

	      oo++
	      XXmmFFIILLEE__DDIIRREECCTTOORRYY restricts the file list to contain only direc-
	      tories.

	      oo++
	      XXmmFFIILLEE__AANNYY__TTYYPPEE allows the list to contain all file types
	      including	directories.

  XXmmNNffiilltteerrLLaabbeellSSttrriinngg
	    Specifies the label	string for the text entry field	for the
	    directory mask.  The default for this resource depends on the
	    locale.  In	the C locale the default is "Filter".

  XXmmNNlliissttUUppddaatteedd
	    Specifies an attribute that	is set only by the directory and file
	    search procedures.	Set to True if the search procedure updated
	    the	directory or file list.

  XXmmNNnnooMMaattcchhSSttrriinngg
	    Specifies a	string to be displayed in the file list	if the list
	    of files is	empty.

  XXmmNNppaatttteerrnn
	    Specifies the search pattern used in combination with XXmmNNddiirreecc--
	    ttoorryy in determining	the files and directories to be	displayed.
	    The	default	value is determined by the XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc
	    and	depends	on the initial values of XXmmNNddiirrMMaasskk, XXmmNNddiirreeccttoorryy,
	    and	XXmmNNppaatttteerrnn.  If	the default is NULL or empty, a	pattern	that
	    matches all	files is used.

  XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc
	    Specifies a	search data qualification procedure to replace the
	    default data qualification procedure.  FileSelectionBox's default
	    data qualification procedure fulfills the needs of most applica-
	    tions.  Because it is impossible to	cover the requirements of all
	    applications, you can replace the default procedure.

	    The	data qualification procedure is	called to generate a quali-
	    fied directory mask, base directory, and search pattern for	use
	    by the directory and file search procedures.  It is	called with
	    three arguments: the FileSelectionBox widget and pointers to two
	    XXmmFFiilleeSSeelleeccttiioonnBBooxxCCaallllbbaacckkSSttrruucctt structures.  The first callback
	    struct contains the	input data.  The second	callback struct	con-
	    tains the output data, to be filled	in by the data qualification
	    procedure.

	    If the input _d_i_r and _p_a_t_t_e_r_n members are not NULL, the procedure
	    must copy them to the corresponding	members	of the output call-
	    back struct.





	    If the input _d_i_r is	NULL, the procedure constructs the output _d_i_r
	    as follows:	If the input _m_a_s_k member is NULL, the procedure	uses
	    the	widget's XXmmNNddiirreeccttoorryy as the output _d_i_r; otherwise, it
	    extracts the output	_d_i_r from the input _m_a_s_k.  If the resulting
	    output _d_i_r is empty, the procedure uses the	current	working
	    directory instead.

	    If the input _p_a_t_t_e_r_n is NULL, the procedure	constructs the output
	    _p_a_t_t_e_r_n as follows:	If the input _m_a_s_k member is NULL, the pro-
	    cedure uses	the widget's XXmmNNppaatttteerrnn	as the output _p_a_t_t_e_r_n; other-
	    wise, it extracts the output _p_a_t_t_e_r_n from the input	_m_a_s_k.  If the
	    resulting output _p_a_t_t_e_r_n is	empty, the procedure uses a pattern
	    that matches all files instead.

	    The	data qualification procedure constructs	the output _m_a_s_k	from
	    the	output _d_i_r and _p_a_t_t_e_r_n.	 The procedure must ensure that	the
	    output _d_i_r,	_p_a_t_t_e_r_n, and _m_a_s_k are fully qualified.

	    If the input _v_a_l_u_e member is not NULL, the procedure must copy it
	    to the output _v_a_l_u_e	member;	otherwise, the procedure must copy
	    the	widget's XXmmNNddiirrSSppeecc to the output _v_a_l_u_e.

	    The	data qualification procedure must calculate the	lengths	of
	    the	output _v_a_l_u_e, _m_a_s_k, _d_i_r, and _p_a_t_t_e_r_n members and must fill in
	    the	corresponding length members of	the output callback struct.

	    The	data qualification procedure must copy the input _r_e_a_s_o_n	and
	    _e_v_e_n_t members to the corresponding output members.

  The values of	the XXmmNNddiirrSSeeaarrcchhPPrroocc and XXmmNNffiilleeSSeeaarrcchhPPrroocc are procedure
  pointers of type XXmmSSeeaarrcchhPPrroocc, defined as follows:


  vvooiidd ((** XXmmSSeeaarrcchhPPrroocc))	((_w, _s_e_a_r_c_h__d_a_t_a))
       WWiiddggeett _w;;
       XXttPPooiinntteerr_s_e_a_r_c_h__d_a_t_a;;

  _w	    The	FileSelectionBox widget

  _s_e_a_r_c_h__d_a_t_a
	    Pointer to an XXmmFFiilleeSSeelleeccttiioonnBBooxxCCaallllbbaacckkSSttrruucctt containing infor-
	    mation for conducting a search



  The value of the XXmmNNqquuaalliiffyySSeeaarrcchhDDaattaaPPrroocc resource is	a procedure pointer
  of type XXmmQQuuaalliiffyyPPrroocc, defined as follows:


  vvooiidd ((** XXmmQQuuaalliiffyyPPrroocc)) ((_w, _i_n_p_u_t__d_a_t_a, _o_u_t_p_u_t__d_a_t_a))
       WWiiddggeett _w;;
       XXttPPooiinntteerr_i_n_p_u_t__d_a_t_a;;
       XXttPPooiinntteerr_o_u_t_p_u_t__d_a_t_a;;

  _w	    The	FileSelectionBox widget

  _i_n_p_u_t__d_a_t_a
	    Pointer to an XXmmFFiilleeSSeelleeccttiioonnBBooxxCCaallllbbaacckkSSttrruucctt containing input
	    data to be qualified

  _o_u_t_p_u_t__d_a_t_a
	    Pointer to an XXmmFFiilleeSSeelleeccttiioonnBBooxxCCaallllbbaacckkSSttrruucctt containing output
	    data to be filled in by the	qualification procedure



  Inherited Resources

  FileSelectionBox inherits behavior and resources from	the following superc-
  lasses.  For a complete description of each resource,	refer to the man page
  for that superclass.

			  XXmmSSeelleeccttiioonnBBooxx RReessoouurrccee SSeett
       _________________________________________________________________
       NNaammee			       DDeeffaauulltt			  AAcccceessss
	     CCllaassss			     TTyyppee
       _________________________________________________________________
       _________________________________________________________________
       XmNapplyCallback		       NULL			  C
	     XmCCallback		      XtCallbackList
       _________________________________________________________________
       XmNapplyLabelString	       dynamic			  CSG
	     XmCApplyLabelString	      XmString
       _________________________________________________________________
       XmNcancelCallback	       NULL			  C
	     XmCCallback		      XtCallbackList
       _________________________________________________________________
       XmNcancelLabelString	       dynamic			  CSG
	     XmCCancelLabelString	      XmString
       _________________________________________________________________
       XmNchildPlacement	       XmPLACE_ABOVE_SELECTION	  CSG
	     XmCChildPlacement		      unsigned char
       _________________________________________________________________
       XmNdialogType		       XmDIALOG_FILE_SELECTION	  G
	     XmCDialogType		      unsigned char
       _________________________________________________________________
       XmNhelpLabelString	       dynamic			  CSG
	     XmCHelpLabelString		      XmString
       _________________________________________________________________
       XmNlistItemCount		       dynamic			  CSG
	     XmCItemCount		      int
       _________________________________________________________________
       XmNlistItems		       dynamic			  CSG
	     XmCItems			      XmStringTable
       _________________________________________________________________
       XmNlistLabelString	       dynamic			  CSG
	     XmCListLabelString		      XmString
       _________________________________________________________________
       XmNlistVisibleItemCount	       dynamic			  CSG
	     XmCVisibleItemCount	      int
       _________________________________________________________________
       XmNminimizeButtons	       False			  CSG
	     XmCMinimizeButtons		      Boolean
       _________________________________________________________________
       XmNmustMatch		       False			  CSG
	     XmCMustMatch		      Boolean
       _________________________________________________________________
       XmNnoMatchCallback	       NULL			  C
	     XmCCallback		      XtCallbackList
       _________________________________________________________________
       XmNokCallback		       NULL			  C
	     XmCCallback		      XtCallbackList
       _________________________________________________________________
       XmNokLabelString		       dynamic			  CSG
	     XmCOkLabelString		      XmString
       _________________________________________________________________
       XmNselectionLabelString	       dynamic			  CSG
	     XmCSelectionLabelString	      XmString
       _________________________________________________________________
       XmNtextAccelerators	       default			  C
	     XmCTextAccelerators	      XtAccelerators
       _________________________________________________________________
       XmNtextColumns		       dynamic			  CSG
	     XmCColumns			      short
       _________________________________________________________________
       XmNtextString		       dynamic			  CSG
	     XmCTextString		      XmString
       _________________________________________________________________

			 XXmmBBuulllleettiinnBBooaarrdd RReessoouurrccee SSeett
	   _________________________________________________________
	   NNaammee			      DDeeffaauulltt		      AAcccceessss
		 CCllaassss			    TTyyppee
	   _________________________________________________________
	   _________________________________________________________
	   XmNallowOverlap	      True		      CSG
		 XmCAllowOverlap	     Boolean
	   _________________________________________________________
	   XmNautoUnmanage	      False		      CG
		 XmCAutoUnmanage	     Boolean
	   _________________________________________________________
	   XmNbuttonFontList	      dynamic		      CSG
		 XmCButtonFontList	     XmFontList
	   _________________________________________________________
	   XmNcancelButton	      Cancel button	      SG
		 XmCWidget		     Widget
	   _________________________________________________________
	   XmNdefaultButton	      OK button		      SG
		 XmCWidget		     Widget
	   _________________________________________________________
	   XmNdefaultPosition	      True		      CSG
		 XmCDefaultPosition	     Boolean
	   _________________________________________________________
	   XmNdialogStyle	      dynamic		      CSG
		 XmCDialogStyle		     unsigned char
	   _________________________________________________________
	   XmNdialogTitle	      NULL		      CSG
		 XmCDialogTitle		     XmString
	   _________________________________________________________
	   XmNfocusCallback	      NULL		      C
		 XmCCallback		     XtCallbackList
	   _________________________________________________________
	   XmNlabelFontList	      dynamic		      CSG
		 XmCLabelFontList	     XmFontList
	   _________________________________________________________
	   XmNmapCallback	      NULL		      C
		 XmCCallback		     XtCallbackList
	   _________________________________________________________
	   XmNmarginHeight	      10		      CSG
		 XmCMarginHeight	     Dimension
	   _________________________________________________________
	   XmNmarginWidth	      10		      CSG
		 XmCMarginWidth		     Dimension
	   _________________________________________________________
	   XmNnoResize		      False		      CSG
		 XmCNoResize		     Boolean
	   _________________________________________________________
	   XmNresizePolicy	      XmRESIZE_ANY	      CSG
		 XmCResizePolicy	     unsigned char
	   _________________________________________________________
	   XmNshadowType	      XmSHADOW_OUT	      CSG
		 XmCShadowType		     unsigned char
	   _________________________________________________________
	   XmNtextFontList	      dynamic		      CSG
		 XmCTextFontList	     XmFontList
	   _________________________________________________________
	   XmNtextTranslations	      NULL		      C
		 XmCTranslations	     XtTranslations
	   _________________________________________________________
	   XmNunmapCallback	      NULL		      C
		 XmCCallback		     XtCallbackList
	   _________________________________________________________


			    XXmmMMaannaaggeerr RReessoouurrccee SSeett
	_______________________________________________________________
	NNaammee			      DDeeffaauulltt			 AAcccceessss
	      CCllaassss			    TTyyppee
	_______________________________________________________________
	_______________________________________________________________
	XmNbottomShadowColor	      dynamic			 CSG
	      XmCBottomShadowColor	     Pixel
	_______________________________________________________________
	XmNbottomShadowPixmap	      XmUNSPECIFIED_PIXMAP	 CSG
	      XmCBottomShadowPixmap	     Pixmap
	_______________________________________________________________
	XmNforeground		      dynamic			 CSG
	      XmCForeground		     Pixel
	_______________________________________________________________
	XmNhelpCallback		      NULL			 C
	      XmCCallback		     XtCallbackList
	_______________________________________________________________
	XmNhighlightColor	      dynamic			 CSG
	      XmCHighlightColor		     Pixel
	_______________________________________________________________
	XmNhighlightPixmap	      dynamic			 CSG
	      XmCHighlightPixmap	     Pixmap
	_______________________________________________________________
	XmNinitialFocus		      dynamic			 CSG
	      XmCInitialFocus		     Widget
	_______________________________________________________________
	XmNnavigationType	      XmTAB_GROUP		 CSG
	      XmCNavigationType		     XmNavigationType
	_______________________________________________________________
	XmNshadowThickness	      dynamic			 CSG
	      XmCShadowThickness	     Dimension
	_______________________________________________________________
	XmNstringDirection	      dynamic			 CG
	      XmCStringDirection	     XmStringDirection
	_______________________________________________________________
	XmNtopShadowColor	      dynamic			 CSG
	      XmCTopShadowColor		     Pixel
	_______________________________________________________________
	XmNtopShadowPixmap	      dynamic			 CSG
	      XmCTopShadowPixmap	     Pixmap
	_______________________________________________________________
	XmNtraversalOn		      True			 CSG
	      XmCTraversalOn		     Boolean
	_______________________________________________________________
	XmNunitType		      dynamic			 CSG
	      XmCUnitType		     unsigned char
	_______________________________________________________________
	XmNuserData		      NULL			 CSG
	      XmCUserData		     XtPointer
	_______________________________________________________________

			    CCoommppoossiittee RReessoouurrccee SSeett
	     _____________________________________________________
	     NNaammee		       DDeeffaauulltt		    AAcccceessss
		   CCllaassss		     TTyyppee
	     _____________________________________________________
	     _____________________________________________________
	     XmNchildren	       NULL		    G
		   XmCReadOnly		      WidgetList
	     _____________________________________________________
	     XmNinsertPosition	       NULL		    CSG
		   XmCInsertPosition	      XtOrderProc
	     _____________________________________________________
	     XmNnumChildren	       0		    G
		   XmCReadOnly		      Cardinal
	     _____________________________________________________

			      CCoorree RReessoouurrccee SSeett
     ____________________________________________________________________
     NNaammee				   DDeeffaauulltt		   AAcccceessss
	   CCllaassss				 TTyyppee
     ____________________________________________________________________
     ____________________________________________________________________
     XmNaccelerators			   dynamic		   N/A
	   XmCAccelerators			  XtAccelerators
     ____________________________________________________________________
     XmNancestorSensitive		   dynamic		   G
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNbackground			   dynamic		   CSG
	   XmCBackground			  Pixel
     ____________________________________________________________________
     XmNbackgroundPixmap		   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderColor			   XtDefaultForeground	   CSG
	   XmCBorderColor			  Pixel
     ____________________________________________________________________
     XmNborderPixmap			   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderWidth			   0			   CSG
	   XmCBorderWidth			  Dimension
     ____________________________________________________________________
     XmNcolormap			   dynamic		   CG
	   XmCColormap				  Colormap
     ____________________________________________________________________
     XmNdepth				   dynamic		   CG
	   XmCDepth				  int
     ____________________________________________________________________
     XmNdestroyCallback			   NULL			   C
	   XmCCallback				  XtCallbackList
     ____________________________________________________________________
     XmNheight				   dynamic		   CSG
	   XmCHeight				  Dimension
     ____________________________________________________________________
     XmNinitialResourcesPersistent	   True			   C
	   XmCInitialResourcesPersistent	  Boolean
     ____________________________________________________________________
     XmNmappedWhenManaged		   True			   CSG
	   XmCMappedWhenManaged			  Boolean
     ____________________________________________________________________
     XmNscreen				   dynamic		   CG
	   XmCScreen				  Screen *
     ____________________________________________________________________
     XmNsensitive			   True			   CSG
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNtranslations			   dynamic		   CSG
	   XmCTranslations			  XtTranslations
     ____________________________________________________________________
     XmNwidth				   dynamic		   CSG
	   XmCWidth				  Dimension
     ____________________________________________________________________
     XmNx				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________
     XmNy				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________

  Callback Information

  A pointer to the following structure is passed to each callback:


  ttyyppeeddeeff ssttrruucctt
  {{
    iinntt	     _r_e_a_s_o_n;;
    XXEEvveenntt   * _e_v_e_n_t;;
    XXmmSSttrriinngg _v_a_l_u_e;;
    iinntt	     _l_e_n_g_t_h;;
    XXmmSSttrriinngg _m_a_s_k;;
    iinntt	     _m_a_s_k__l_e_n_g_t_h;;
    XXmmSSttrriinngg _d_i_r;;
    iinntt	     _d_i_r__l_e_n_g_t_h;;
    XXmmSSttrriinngg _p_a_t_t_e_r_n;;
    iinntt	     _p_a_t_t_e_r_n__l_e_n_g_t_h;;
  }} XXmmFFiilleeSSeelleeccttiioonnBBooxxCCaallllbbaacckkSSttrruucctt;;

  _r_e_a_s_o_n    Indicates why the callback was invoked

  _e_v_e_n_t	    Points to the XXEEvveenntt that triggered	the callback

  _v_a_l_u_e	    Specifies the current value	of XXmmNNddiirrSSppeecc

  _l_e_n_g_t_h    Specifies the number of bytes in _v_a_l_u_e

  _m_a_s_k	    Specifies the current value	of XXmmNNddiirrMMaasskk

  _m_a_s_k__l_e_n_g_t_h
	    Specifies the number of bytes in _m_a_s_k

  _d_i_r	    Specifies the current base directory

  _d_i_r__l_e_n_g_t_h
	    Specifies the number of bytes in _d_i_r

  _p_a_t_t_e_r_n   Specifies the current search pattern

  _p_a_t_t_e_r_n__l_e_n_g_t_h
	    Specifies the number of bytes in _p_a_t_t_e_r_n

  Translations

  XmFileSelectionBox inherits translations from	XmSelectionBox.

  Accelerators

  The XXmmNNtteexxttAAcccceelleerraattoorrss from XmSelectionBox are added	to the selection and
  directory mask (filter) Text descendants of XmFileSelectionBox.

  Action Routines

  The XmFileSelectionBox action	routines are described below:

  SSeelleeccttiioonnBBooxxUUppOOrrDDoowwnn((00||11||22||33)):
	    If neither the selection text nor the directory mask (filter)
	    text has the focus,	this action does nothing.


	    If the selection text has the focus, the term _l_i_s_t in the follow-
	    ing	description refers to the file list, and the term _t_e_x_t refers
	    to the selection text.  If the directory mask text has the focus,
	    _l_i_s_t refers	to the directory list, and _t_e_x_t	refers to the direc-
	    tory mask text.

	    When called	with a 0 argument, selects the previous	item in	the
	    list and replaces the text with that item.

	    When called	with a 1 argument, selects the next item in the	list
	    and	replaces the text with that item.

	    When called	with a 2 argument, selects the first item in the list
	    and	replaces the text with that item.

	    When called	with a 3 argument, selects the last item in the	list
	    and	replaces the text with that item.

  SSeelleeccttiioonnBBooxxRReessttoorree(()):
	    If neither the selection text nor the directory mask (filter)
	    text has the focus,	this action does nothing.

	    If the selection text has the focus, replaces the selection	text
	    with the selected item in the file list.  If no item in the	file
	    list is selected, clears the selection text.

	    If the directory mask text has the focus, replaces the directory
	    mask text with a new directory mask	constructed from the
	    XXmmNNddiirreeccttoorryy and XXmmNNppaatttteerrnn	resources.

  Additional Behavior

  The FileSelectionBox widget has the additional behavior described below:

  MMAAnnyy KKCCaanncceell:
	    Calls the activate callbacks for the cancel	button if it is	sen-
	    sitive.  If	no cancel button exists	and the	parent of the
	    FileSelectionBox is	a manager, passes the event to the parent.

  <<KKAAccttiivvaattee>> in Selection Text:
	    Calls the selection	text widget's XXmmNNaaccttiivvaatteeCCaallllbbaacckk callbacks.
	    If XXmmNNmmuussttMMaattcchh is True and	the selection text does	not match an
	    item in the	file list, calls the XXmmNNnnooMMaattcchhCCaallllbbaacckk	callbacks
	    with reason	XXmmCCRR__NNOO__MMAATTCCHH.	Otherwise, calls the XXmmNNookkCCaallllbbaacckk
	    callbacks with reason XXmmCCRR__OOKK.

  <<KKAAccttiivvaattee>> in Directory Mask	Text:
	    Calls the directory	mask text widget's XXmmNNaaccttiivvaatteeCCaallllbbaacckk call-
	    backs.  Initiates a	directory and file search.  Calls the XXmmNNaapp--
	    ppllyyCCaallllbbaacckk	callbacks with reason XXmmCCRR__AAPPPPLLYY.

  <<DDoouubblleeCClliicckk>>	or <<KKAAccttiivvaattee>> in Directory List:
	    Calls the directory	list widget's XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk call-
	    backs.  Initiates a	directory and file search.  Calls the XXmmNNaapp--
	    ppllyyCCaallllbbaacckk	callbacks with reason XXmmCCRR__AAPPPPLLYY.

  <<DDoouubblleeCClliicckk>>	or <<KKAAccttiivvaattee>> in File List:
	    Calls the file list	widget's XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk callbacks.
	    Calls the XXmmNNookkCCaallllbbaacckk callbacks with reason XXmmCCRR__OOKK.

  <<SSiinnggllee SSeelleecctt>> or <<BBrroowwssee SSeelleecctt>> in	Directory List:
	    Generates a	new directory mask, using the selected list item as
	    the	directory and the pattern extracted from the current direc-
	    tory mask text as the search pattern.  If the search pattern is
	    empty, uses	a pattern that matches all files in the	directory.
	    Replaces the directory mask	text with the new directory mask.

  <<SSiinnggllee SSeelleecctt>> or <<BBrroowwssee SSeelleecctt>> in	File List:
	    Replaces the selection text	with the selected list item.

  <<BBDDrraagg>> in File List:
	    Drags the content of one or	more selected list items using the
	    drag and drop facility.  If	BBDDrraagg is pressed on an unselected
	    item, drags	only that item,	excluding any other selected items.

	    The	XXmmNNeexxppoorrttTTaarrggeettss resource of the associated DragContext	is
	    set	to target types	of COMPOUND_TEXT and FILE_NAME.	 The
	    XXmmNNcclliieennttDDaattaa resource is set to the index of the item in the
	    list.

  <<BBDDrraagg>> in Directory List:
	    Drags the content of one or	more selected list items using the
	    drag and drop facility.  If	BBDDrraagg is pressed on an unselected
	    item, drags	only that item,	excluding any other selected items.

	    The	XXmmNNeexxppoorrttTTaarrggeettss resource of the associated DragContext	is
	    set	to target types	of COMPOUND_TEXT and FILE_NAME.	 The
	    XXmmNNcclliieennttDDaattaa resource is set to the index of the item in the
	    list.

  <<AAppppllyy BBuuttttoonn	AAccttiivvaatteedd>>:
	    Initiates a	directory and file search.  Calls the XXmmNNaappppllyyCCaallll--
	    bbaacckk callbacks with	reason XXmmCCRR__AAPPPPLLYY.

  <<OOKK BBuuttttoonn AAccttiivvaatteedd>>:
	    If XXmmNNmmuussttMMaattcchh is True and	the selection text does	not match an
	    item in the	file list, calls the XXmmNNnnooMMaattcchhCCaallllbbaacckk	callbacks
	    with reason	XXmmCCRR__NNOO__MMAATTCCHH.	Otherwise, calls the XXmmNNookkCCaallllbbaacckk
	    callbacks with reason XXmmCCRR__OOKK.

  <<CCaanncceell BBuuttttoonn AAccttiivvaatteedd>>:
	    Calls the XXmmNNccaanncceellCCaallllbbaacckk	callbacks with reason XXmmCCRR__CCAANNCCEELL.

  <<HHeellpp	BBuuttttoonn AAccttiivvaatteedd>>:
	    Calls the XXmmNNhheellppCCaallllbbaacckk callbacks	with reason XXmmCCRR__HHEELLPP.

  <<KKAAccttiivvaattee>>:
	    If no button, list widget, or text widget has the keyboard focus:
	    If XXmmNNmmuussttMMaattcchh is True and	the selection text does	not match an
	    item in the	file list, calls the XXmmNNnnooMMaattcchhCCaallllbbaacckk	callbacks
	    with reason	XXmmCCRR__NNOO__MMAATTCCHH.	Otherwise, calls the XXmmNNookkCCaallllbbaacckk
	    callbacks with reason XXmmCCRR__OOKK.

  Virtual Bindings

  The bindings for virtual keys	are vendor specific.  For information about
  bindings for virtual buttons and keys, see VViirrttuuaallBBiinnddiinnggss((33XX)).

RELATED	INFORMATION
  CCoommppoossiittee((33XX)), CCoonnssttrraaiinntt((33XX)), CCoorree((33XX)), XXmmBBuulllleettiinnBBooaarrdd((33XX)),
  XXmmCCrreeaatteeFFiilleeSSeelleeccttiioonnBBooxx((33XX)),	XXmmCCrreeaatteeFFiilleeSSeelleeccttiioonnDDiiaalloogg((33XX)),
  XXmmFFiilleeSSeelleeccttiioonnBBooxxGGeettCChhiilldd((33XX)), XXmmFFiilleeSSeelleeccttiioonnDDooSSeeaarrcchh((33XX)), XXmmMMaannaaggeerr((33XX)),
  and XXmmSSeelleeccttiioonnBBooxx((33XX)).















