Name

DwtFileSelection, DwtFileSelectionCreate − Creates a file selection box widget for the application to query the user for a file selection. 

Syntax

Widget DwtFileSelection(parent_widget, name, x, y,
                        title, value, dirmask,
                        visible_items_count, style, default_position,
                        default_position, callback,
                        help_callback)
     Widget parent_widget;
     char *name;
     Position x, y;
     DwtCompString title;
     DwtCompString value;
     DwtCompString dirmask;
     int visible_items_count;
     int style;
     Boolean default_position;
     DwtCallbackPtr callback, help_callback;

Widget DwtFileSelectionCreate (parent_widget, name,
                               override_arglist,
                               override_argcount)
     Widget parent_widget;
     char *name;
     ArgList override_arglist;
     int override_argcount;

Arguments

parent_widget
Specifies the parent widget ID.

nameSpecifies the name of the created widget. 

xSpecifies the placement, in pixels, of the left side of the widget window relative to the inner upper left corner of the parent window.  This argument sets the DwtNx core widget attribute. 

ySpecifies, in pixels, the placement of the upper left corner of the widget window relative to the inner upper left corner of the parent window.  This argument sets the DwtNy core widget attribute. 

titleSpecifies the text that appears in the banner of the file selection box.  This argument sets the DwtNtitle attribute associated with DwtDialogBoxPopupCreate. 

valueSpecifies the selected file.  The file name appears in the text entry field and is highlighted in the list box, if present.  This argument sets the DwtNvalue attribute associated with DwtSelectionCreate. 

dirmaskSpecifies the directory mask used in determining the files displayed in the file selection list box.  This argument sets the DwtNdirMask attribute associated with DwtFileSelectionCreate. 

visible_items_count
Specifies the maximum number of files visible at one time in the file selection list box. This argument sets the DwtNvisibleItemsCount attribute associated with DwtSelectionCreate. 

styleSpecifies the style of the pop-up dialog box widget.  You can pass DwtModal (modal) or DwtModeless (modeless).  This argument sets the DwtNstyle attribute associated with DwtDialogBoxPopupCreate. 

default_position
Specifies a boolean value that, when True, causes DwtNx and DwtNy to be ignored and forces the default widget position.  The default widget position is centered in the parent window.  If False, the specified DwtNx and DwtNy attributes are used to position the widget.  This argument sets the DwtNdefaultPosition attribute associated with DwtDialogBoxCreate. 

callbackSpecifies the callback function or functions called when the user makes or cancels a selection, or there is no match for the item selected by the user.  This argument sets the DwtNactivateCallback, DwtNcancelCallback, and DwtNnoMatchCallback attributes associated with DwtSelectionCreate. 

help_callbackSpecifies the callback function or functions called when a help request is made.  This argument sets the DwtNhelpCallback common widget attribute. 

parent_widget
Specifies the parent widget ID.

nameSpecifies the name of the created widget. 

override_arglist
Specifies the application override argument list.

override_argcount
Specifies the number of attributes in the application override argument list (override_arglist). 

Description

The DwtFileSelection and DwtFileSelectionCreate functions create an instance of a file selection widget for the application to query the user for a file selection and return its associated widget ID.  When calling DwtFileSelection, you set the file selection box widget attributes presented in the formal parameter list.  For DwtFileSelectionCreate, however, you specify a list of attribute name/value pairs that represent all the possible file selection box widget attributes. 

This is a subclass of the selection widget, which is a subclass of the dialog widget.  The file selection widget is a specialized pop-up dialog box, supporting either modal or modeless formats. 

A file selection widget contains the following:

•A list box displaying the file names from which to choose

•A directory mask text entry field

•A selection text entry field

•An Apply push button to apply the dirmask to generate a new list of files

•An Ok push button to inform the application that the user made a selection

•A Cancel push button to inform the application that the user canceled a selection

Note that the callback data structure also includes the current DwtNvalue and DwtNdirMask.  This allows user input text and directory information to be passed back. 

The file selection widget supports remote file search between nodes on a network.  You can perform remote file searches from VMS to ULTRIX systems, but currently not from ULTRIX to VMS systems. 

Inherited Attributes

Widget-Specific Attributes

DwtNfilterLabel
Specifies the label for the search filter located above the text-entry field.

DwtNapplyLabelSpecifies the label for the Apply push button. 

DwtNdirMaskSpecifies the directory mask used in determining the files displayed in the file selection list box. 

DwtNdirSpecSpecifies the full ULTRIX file specification.  This attribute is write only and cannot be modified by XtSetValues. 

DwtNfileSearchProc
Specifies a directory search procedure to replace the default file selection search procedure. The file selection widget’s default file search procedure fulfills the needs of most applications. However, it is impossible to cover the requirements of all applications; therefore, you can replace the default search procedure.

You call the file search procedure with two arguments: the file selection widget and the DwtFileSelectionCallbackStruct structure.  The callback structure contains all required information to conduct a directory search, including the current file search mask.  Once called, it is up to the search routine to generate a new list of files and update the file selection widget by using XtSetValues. 

You must set these attributes: DwtNitems, DwtNitemsCount, DwtNlistUpdated, and DwtNdirSpec.  Set DwtNitems to the new list of files.  If there are no files, set this attribute to NULL.  This argument sets the DwtNitems attribute associated with DwtSelectionCreate. 

If there are no files set DwtNitemsCount to zero.  This argument sets the DwtNitemsCount associated with DwtSelectionCreate.  Always set DwtNlistUpdated to True when updating the file list using a search procedure, even if there are no files.  Setting DwtNdirSpec is optional, but recommended.  Set this attribute to the full file specification of the directory searched.  The directory specification is displayed above the list box. 

DwtNlistUpdated
Specifies an attribute that is set only by the file search procedure. Set to True, if the file list has been updated. 

DwtNfileToExternProc
Converts native, internal file names to custom, external file names displayed to the user.

DwtNfileToInternProc
Converts custom, external file names displayed to the user to native, internal file names.

DwtNmaskToExternProc
Converts native, internal directory masks to custom, external directory masks displayed to the user.

DwtNmaskToInternProc
Converts custom, external directory masks displayed to the user to native, internal directory masks.

Return Values

These functions return the ID of the created widget. 

Callback Information

The following structure is returned to your callback:

typedef struct {
int reason;
XEvent *event;
DwtCompString value;
int value_len;
DwtCompString dirmask;
int dirmask_len;
} DwtFileSelectionCallbackStruct;

The reason member is set to a constant that represents the reason why this callback was invoked. For this callback, the reason member can be set to:

The event member is a pointer to the Xlib structure XEvent, which describes the event that generated this callback.  This structure is a union of the individual structures declared for each event type.  For information on XEvent and event processing, see the Guide to the Xlib Library: C Language Binding.  The value member is set to the current selection when the callback occurred.  The value_len member is set to the length of the selection compound-string.  The dirmask member is set to the current directory mask when the callback occurred.  The dirmask_len member is set to the length of the directory mask compound-string. 

See Also

Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding