DwtFileSelection(3Dwt) DwtFileSelection(3Dwt)
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.
name Specifies the name of the created widget.
x Specifies 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.
y Specifies, 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.
title Specifies the text that appears in the banner of the file selection box. This argument sets the DwtNtitle attribute associated
with DwtDialogBoxPopupCreate.
value Specifies 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.
dirmask Specifies the directory mask used in determining the files displayed in the file selection list box. This argument sets the Dwt-
NdirMask 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 DwtNvisibleIt-
emsCount attribute associated with DwtSelectionCreate.
style Specifies 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 posi-
tion the widget. This argument sets the DwtNdefaultPosition attribute associated with DwtDialogBoxCreate.
callback Specifies 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 asso-
ciated with DwtSelectionCreate.
help_callback
Specifies 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.
name Specifies 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:
o A list box displaying the file names from which to choose
o A directory mask text entry field
o A selection text entry field
o An Apply push button to apply the dirmask to generate a new list of files
o An Ok push button to inform the application that the user made a selection
o 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
-----------------------------------------------------------------------
Attribute Name Data Type Default
-----------------------------------------------------------------------
Core Attributes
DwtNx Position Centered in the parent
window
DwtNy Position Centered in the parent
window
DwtNwidth Dimension The width of the list
box, plus the width of
the push buttons, plus
three times DwtNmargin-
Width. The list box
will grow to accommodate
items wider than the
title.
DwtNheight Dimension The height of the list
box, plus the height of
the text edit field,
plus the height of the
label, plus three times
DwtNmarginHeight.
DwtNborderWidth Dimension One pixel
DwtNborder Pixel Default foreground color
DwtNborderPixmap Pixmap NULL
DwtNbackground Pixel Default background color
DwtNbackgroundPixmap Pixmap NULL
DwtNcolormap Colormap Default color map
DwtNsensitive Boolean True
DwtNancestorSensitive Boolean The bitwise AND of the
parent widget's DwtNsen-
sitive and DwtNances-
torSensitive attributes
DwtNaccelerators XtTranslations NULL
DwtNdepth int Depth of the parent win-
dow
DwtNtranslations XtTranslations NULL
DwtNmappedWhenManaged Boolean True
DwtNscreen Screen * The parent screen
DwtNdestroyCallback DwtCallbackPtr NULL
Dialog Pop-Up Attributes
DwtNforeground Pixel Default foreground color
DwtNhighlight Pixel Default foreground color
DwtNhighlightPixmap Pixmap NULL
DwtNuserData Opaque * NULL
DwtNfont DwtFontList The default XUI Toolkit
font
DwtNhelpCallback DwtCallbackPtr NULL
DwtNdirectionRToL unsigned char DwtDirectionRightDown
DwtNunits unsigned char DwtFontUnits
DwtNstyle unsigned char DwtModal
DwtNfocusCallback DwtCallbackPtr NULL
DwtNtextMergeTranslations XtTranslations NULL
DwtNmarginWidth Dimension 5 pixels
DwtNmarginHeight Dimension 5 pixels
DwtNdefaultPosition Boolean False
DwtNchildOverlap Boolean True
DwtNresize unsigned char DwtResizeGrowOnly
DwtNnoResize Boolean True (that is, no window
manager resize button)
DwtNtitle DwtCompString "Open"
DwtNmapCallback DwtCallbackPtr NULL
DwtNunmapCallback DwtCallbackPtr NULL
DwtNtakeFocus Boolean True for modal dialog
box
False for modeless dia-
log box
DwtNautoUnmanage Boolean True
DwtNdefaultButton Widget NULL
DwtNcancelButton Widget NULL
Selection Attributes
DwtNlabel DwtCompString "Items"
DwtNvalue DwtCompString ""
DwtNokLabel DwtCompString "Ok"
DwtNcancelLabel DwtCompString "Cancel"
DwtNactivateCallback DwtCallbackPtr NULL
DwtNcancelCallback DwtCallbackPtr NULL
DwtNnoMatchCallback DwtCallbackPtr NULL
DwtNvisibleItemsCount int 8
DwtNitems DwtCompString * NULL
DwtNitemsCount int Zero
DwtNmustMatch Boolean False
DwtNselectionLabel DwtCompString "Files in"
-----------------------------------------------------------------------
Widget-Specific Attributes
-------------------------------------------------------
Attribute Name Data Type Default
-------------------------------------------------------
DwtNfilterLabel DwtCompString "File filter"
DwtNapplyLabel DwtCompString "Filter"
DwtNdirMask DwtCompString "*.*"
DwtNdirSpec DwtCompString ""
DwtNfileSearchProc VoidProc FileSelection-
Search (ULTRIX
default direc-
tory file
search func-
tion)
DwtNlistUpdated Boolean False
DwtNfileToExternProc VoidProc NULL
DwtNfileToInternProc VoidProc NULL
DwtNmaskToExternProc VoidProc NULL
DwtNmaskToInternProc VoidProc NULL
-------------------------------------------------------
DwtNfilterLabel
Specifies the label for the search filter located above the text-entry field.
DwtNapplyLabel Specifies the label for the Apply push button.
DwtNdirMask Specifies the directory mask used in determining the files displayed in the file selection list box.
DwtNdirSpec Specifies 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. Set-
ting 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:
DwtCRActivate The user activated the Ok
push button.
DwtCRCancel The user activated the
Cancel button.
DwtCRHelpRequested The user selected help
somewhere in the file
selection box.
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
DwtFileSelection(3Dwt)