SgFileSelectionBox(3X)
SgFileSelectionBox - The enhanced FileSelectionBox widget
Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.
NAME SgFileSelectionBox - The enhanced FileSelectionBox widget SYNOPSIS #include <Xm/FileSB.h> VERSION This page documents the version of Sgm that accompanies Motif 1.2. DESCRIPTION The enhanced XmFileSelectionBox traverses directories, shows files and subdirectories, and selects files. An enhanced XmFileSelectionBox has three main areas: o A Finder widget, consisting of a text field, zoom bar, drop pocket, and history button. o A scrollable list of filenames and subdirectories o A group of Buttons, labeled OK, Filter, Cancel, and Help The user can select a new directory to examine by scrolling through the list of files and directories and selecting the desired directory. 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 Finder widget consists of a text field, drop pocket, and history button. The text area allows a user to type a file name. The text field will always display the current directory whose files are listed in the XmFileSelectionBox's list widget. It may also display a file name concatenated on the tail of the current directory. The zoom bar is a line of buttons that mimic the structure of the directory in the text field. Pressing on a zoom bar button with the left mouse button sets the current directory to the directory underneath the button in the text field. The last button will not change anything since it will always be either the current directory or a file in the current directory. Pressing on a zoom bar button with the right mouse button will pop-up a menu of subdirectories that are at the same level as the directory underneath the button in the text field. Choosing an entry from one of these menus will set the current directory to the directory corresponding with the menu entry. The history button shows directories. It pops up a menu of visited directories. The history button will have at least 1 entry: the directory in which the XmFileSelectionBox started in. If a user presses OK, the current directory will be added to the history button menu. Selecting an item on the history button menu sets the current directory to that item. The drop pocket allows icons to be dropped into the XmFileSelectionBox. When an icon is dropped, the current directory is set to the location of that icon. If the icon is a file, the filename is also concatenated onto the tail of the current directory. Acceptable icons for drops will change the background color of the drop pocket. If the type of a file is not known, or the file doesn't exist (as in a new file you are specifying), the drop pocket displays the unkown icon (which looks like a round balloon). Unix .. and . directories may be specified in the text edit area. The tilde: ~ can also be used for home directories in the text edit area. The text edit area supports csh-style file completion. While typing, the longest matching substring from the items currently shown in the list is inserted in the text edit area. The current selection is set to the inserted text. You can just keep typing to ignore it, or use shift-space to accept the text. Typing shift-space at any time will extend the the current text to next entry in the list that matches the current text. If there are multiple matches, the current selection will be set to the ambiguous portion. You can then use the up and down arrows to cycle through all of the matching list item. Completion also works on ~ for home directories. The Filter button pops up a dialog asking for a shell style file matching expression. The files in the XmFileSelectionBox's list will be filtered by the expression when the Filter dialog's OK or Apply button is pressed. If the patten does not contain any file matching meta- characters, '*', '?', '[', the patten is assumed to be the name of an FTR file type. After the Filter dialog is cancelled, the file list is updated without any filtering. The XmNpattern resource is set to mirror the filter specified in the filter dialog. If the XmFileSelectionBox came up with a preset XmNpattern, and the user presses Cancel in the Filter dialog, the XmNpattern is set to "*". 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 Selects the OK PushButton o Presses KActivate while the File Selection Box has the keyboard focus and a file is selected. o Double clicks or presses KActivate on a file in the file list. Activate is typically the Enter key. FileSelectionBox initiates a directory and file search when any of the following occurs: o The FileSelectionBox is initialized o The user double clicks or presses KActivate on an item in the directory list Classes FileSelectionBox inherits behavior and resources from Core, Composite, Constraint, XmManager, XmBulletinBoard, and XmSelectionBox. The class pointer is xmFileSelectionBoxWidgetClass. The class name is XmFileSelectionBox. Summary 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). Enhanced XmFileSelectionBox Resource Set Name Class Type Default Access __________________________________________________________________________________________ SgNbrowserFileMask SgCBrowserFileMask unsigned char XmFILE_DIRECTORY CSG SgNcompletionDelay SgCCompletionDelay int 250 CSG SgNuseEnhancedFSB SgCUseEnhancedFSB Boolean True CG SgNviewerMode SgCViewerMode SgRFSBViewerMode SgVIEWER_NEVER CSG SgNviewerFileName SgCViewerFileName XmString NULL CSG SgNviewerFilter SgCViewerFilter XmString "*" CSG SgNviewerUpdateDelay SgCViewerUpdateDelay int 250 CSG SgNbrowserFileMask Specifies the type of files listed in the zoom bar browser menus. Following are the possible values: o XmFILE_REGULAR restricts the browser menu to contain only regular files. o XmFILE_DIRECTORY restricts the browser menu to contain only directories. o SgFILE_NOT_HIDDEN restricts the browser menu to contain only non-hidden files. o XmFILE_ANY_TYPE allows the browser menu to contain all file types including directories. SgNcompletionDelay Specifies the amount of time in miliseconds to wait after the last character is entered in the text field before attempting to automatically invoke the completion function. If this resource is set to zero, auto-completion is disabled. SgNuseEnhancedFSB If true, and the application is linked with -lSgm before -lXm, the enhanced file selection box described by this manual page will be used. If false, the standard Motif file selection box described in XmFileSelectionBox(3X) will be used. This resource can only be set at creation time. SgNviewerMode Specifies the policy for showing and updating the multi-media file viewer. Following are the possible values: o SgVIEWER_NEVER entirely disables the use of the viewer. o SgVIEWER_NONE enables the use of viewer but initially leaves it unmanaged. To manage it later, this resource must be set to either SgVIEWER_AUTOMATIC or SgVIEWER_EXPLICIT. o SgVIEWER_AUTOMATIC enables and manages the viewer. The viewer will automatically be updated as the filename in the finder changes. o SgVIEWER_EXPLICIT enables and manages the viewer. The viewer will always display file indicated by the SgNviewerFileName resource. SgNviewerFileName Specifies the name of the file to be display in the viewer when SgNviewerMode is set to SgVIEWER_EXPLICIT. SgNviewerFilter Specifies the list of file types to be displayed in the viewer when SgNviewerMode is set to SgVIEWER_AUTOMATIC. SgNviewerUpdateDelay Specifies the amount of time in miliseconds to wait after the an item in the list becomes selected before attempting to update the previewer. XmFileSelectionBox Resource Set Name Class Type Default Access _____________________________________________________________________________________ XmNdirectory XmCDirectory XmString dynamic CSG XmNdirSpec XmCDirSpec XmString dynamic SG XmNfileListItems XmCItems XmStringTable dynamic SG XmNfileListItemCount XmCItemCount int dynamic SG XmNfileListLabelString XmCFileListLabelString XmString dynamic CSG XmNfilterLabelString XmCFilterLabelString XmString dynamic CSG XmNnoMatchString XmCNoMatchString XmString " [ ] " CSG XmNpattern XmCPattern XmString "*" CSG XmNdirectory Specifies the base directory used in determining the files and directories to be displayed. If the default is NULL or empty, the current working directory is used. This resource should not be changed by the application after initialization. The application should not free the returned resource. XmNdirSpec Specifies the full file path specification. The default value is determined by the FileSelectionBox after conducting the initial directory and file search. The application should not free this returned resource. XmNfileListItems Specifies the items in the file list. This is the XmNlistItems resource in SelectionBox, renamed for FileSelectionBox. XtGetValues for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. XmNfileListItemCount Specifies the number of items in the file list. This is the XmNlistItemCount resource in SelectionBox, renamed for FileSelectionBox. The value must not be negative. XmNfileListLabelString Specifies the label string of the file list. This is the XmNlistLabelString resource in SelectionBox, renamed for FileSelectionBox. The default for this resource depends on the locale. In the C locale the default is "Files". XmNfilterLabelString 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". XmNnoMatchString Specifies a string to be displayed in the file list if the list of files is empty. XmNpattern Specifies a string used as a regular expression in determining the files to be displayed. The default value is "*" which matches everything. The pattern does not affect display of directories. The format of the pattern is a regular expression of the type described in the ed(1) manual page. If the pattern does not contain any regular expression meta characters, it will be interpreted as a space separated list of FTR file types. Compatibility Resources The following table shows resources for the enhanced XmFileSelectionBox widget which are provided for compatibility with the XmFileSelectionBox. These resources are not used by the enhanced XmFileSelectionBox widget. Their default values may be different from the default in XmFileSelectionBox(3X). For more information on the purpose of these resources in the XmFileSelectionBox(3X), see the man page for XmFileSelectionBox(3X). XmFileSelectionBox Compatibility Resources Name Class Type Default Access _____________________________________________________________________________________________ XmNdirectoryValid XmCDirectoryValid Boolean TRUE SG XmNdirListItems XmCDirListItems XmStringTable NULL SG XmNdirListItemCount XmCDirListItemCount int XmUNSPECIFIED SG XmNdirListLabelString XmCDirListLabelString XmString "" CSG XmNdirMask XmCDirMask XmString "*" CSG XmNdirSearchProc XmCDirSearchProc XmSearchProc NULL CSG XmNfileSearchProc XmCFileSearchProc XmSearchProc NULL CSG XmNfileTypeMask XmCFileTypeMask unsigned char XmFILE_REGULAR CSG XmNlistUpdated XmCListUpdated Boolean TRUE SG XmNqualifySearchDataProc XmCQualifySearchDataProc XmQualifyProc NULL CSG Inherited Resources FileSelectionBox inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. Note that the XmFileSelectionBox widget resets XmNautoUnmanage to FALSE and XmNdialogType to XmDIALOG_FILE_SELECTION. XmSelectionBox Resource Set Name Class Type Default Access ______________________________________________________________________________________________________ XmNapplyCallback XmCCallback XtCallbackList NULL C XmNapplyLabelString XmCApplyLabelString XmString dynamic CSG XmNcancelCallback XmCCallback XtCallbackList NULL C XmNcancelLabelString XmCCancelLabelString XmString dynamic CSG XmNchildPlacement XmCChildPlacement unsigned char XmPLACE_ABOVE_SELECTION CSG XmNdialogType XmCDialogType unsigned char XmDIALOG_FILE_SELECTION G XmNhelpLabelString XmCHelpLabelString XmString dynamic CSG XmNlistItemCount XmCItemCount int dynamic CSG XmNlistItems XmCItems XmStringTable dynamic CSG XmNlistLabelString XmCListLabelString XmString dynamic CSG XmNlistVisibleItemCount XmCVisibleItemCount int dynamic CSG XmNminimizeButtons XmCMinimizeButtons Boolean False CSG XmNmustMatch XmCMustMatch Boolean False CSG XmNnoMatchCallback XmCCallback XtCallbackList NULL C XmNokCallback XmCCallback XtCallbackList NULL C XmNokLabelString XmCOkLabelString XmString dynamic CSG XmNselectionLabelString XmCSelectionLabelString XmString dynamic CSG XmNtextAccelerators XmCTextAccelerators XtAccelerators default C XmNtextColumns XmCColumns short dynamic CSG XmNtextString XmCTextString XmString dynamic CSG XmBulletinBoard Resource Set Name Class Type Default Access __________________________________________________________________________________ XmNallowOverlap XmCAllowOverlap Boolean True CSG XmNautoUnmanage XmCAutoUnmanage Boolean False CG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNcancelButton XmCWidget Widget Cancel button SG XmNdefaultButton XmCWidget Widget OK button SG XmNdefaultPosition XmCDefaultPosition Boolean True CSG XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG XmNdialogTitle XmCDialogTitle XmString NULL CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 10 CSG XmNmarginWidth XmCMarginWidth Dimension 10 CSG XmNnoResize XmCNoResize Boolean False CSG XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNtextTranslations XmCTranslations XtTranslations NULL C XmNunmapCallback XmCCallback XtCallbackList NULL C XmManager Resource Set Name Class Type Default Access _________________________________________________________________________________________________ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget dynamic CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG Composite Resource Set Name Class Type Default Access ______________________________________________________________________ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G Core Resource Set Name Class Type Default Access ______________________________________________________________________________________________________________ XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG Callback Information The Callback structure is XmFileSelectionCallbackStruct. Some fields are not used by the enhanced XmFileSelectionBox. A pointer to the following structure is passed to each callback: typedef struct { int reason; XEvent * event; XmString value; int length; XmString mask; int mask_length; XmString dir; int dir_length; XmString pattern; int pattern_length; } XmFileSelectionBoxCallbackStruct; reason Indicates why the callback was invoked event Points to the XEvent that triggered the callback value Specifies the full pathname of the selected file length Specifies the number of bytes in value mask Not used, always NULL mask_length Not used, always 0. dir Specifies the current base directory, i.e. the parent of the file in value dir_length Specifies the number of bytes in dir pattern Not used, always NULL pattern_length Not used, always 0 Translations XmFileSelectionBox inherits translations from XmSelectionBox. Accelerators The XmNtextAccelerators from XmSelectionBox are added to the selection Text descendant of XmFileSelectionBox. Additional Behavior The FileSelectionBox widget has the additional behavior described below: MAny KCancel: Calls the activate callbacks for the cancel button if it is sensitive. If no cancel button exists and the parent of the FileSelectionBox is a manager, passes the event to the parent. <KActivate> in Selection Text: Calls the selection text widget's XmNactivateCallback callbacks. If XmNmustMatch is True and the selection text does not match an item in the file list, calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, calls the XmNokCallback callbacks with reason XmCR_OK. <DoubleClick> or <KActivate> in File List: Calls the file list widget's XmNdefaultActionCallback callbacks. Calls the XmNokCallback callbacks with reason XmCR_OK. <Single Select> or <Browse Select> in File List: Replaces the selection text with the selected list item. <BDrag> in File List: Drags the content of one or more selected list items using the drag and drop facility. If BDrag is pressed on an unselected item, drags only that item, excluding any other selected items. The XmNexportTargets resource of the associated DragContext is set to target types of COMPOUND_TEXT and FILE_NAME. The XmNclientData resource is set to the index of the item in the list. <OK Button Activated>: If XmNmustMatch is True and the selection text does not match an item in the file list, calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, calls the XmNokCallback callbacks with reason XmCR_OK. <Cancel Button Activated>: Calls the XmNcancelCallback callbacks with reason XmCR_CANCEL. <Help Button Activated>: Calls the XmNhelpCallback callbacks with reason XmCR_HELP. <KActivate>: If no button, list widget, or text widget has the keyboard focus: If XmNmustMatch is True and the selection text does not match an item in the file list, calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, calls the XmNokCallback callbacks with reason XmCR_OK. Virtual Bindings The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X). RELATED INFORMATION Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), SgCreateFileSelectionBox(3X), SgCreateFileSelectionDialog(3X), SgFileSelectionBoxGetChild(3X), XmManager(3X), and XmSelectionBox(3X).