eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'FileDialog':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: FileDialog

Inheritance:

   Object
   |
   +--Model
      |
      +--ApplicationModel
         |
         +--SimpleDialog
            |
            +--FileDialog
               |
               +--FileDialogWithPreview
Package:
stx:libtool
Category:
Interface-Tools-File
Version:
rev: 1.195 date: 2024/03/19 09:08:14
user: cg
file: FileDialog.st directory: libtool
module: stx stc-classLibrary: libtool

Description:


A slightly better file dialog

API of interest:
    [class side] additionalFolderItemsInMenu 
        optional list of additional folders to be presented
        in the directory menu.
        If not empty, entries will be added to EVERY file dialog.

    [instance side] additionalFolderItemsInMenu 
        optional list of additional folders to be presented in the directory menu.
        If not empty, entries will be added to this file dialog.


[instance variables:]

[class variables:]


copyright
COPYRIGHT (c) 2002 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.


todo
- make the filedialog windows like
  filename entry field shows only the filename not the whole directory
  the tree always starts in current directory
  the parent tree is shown in a combobox where the perents are selectable

- do not expand the ~ or relative pathnames to absolute pathnames

Class protocol:

accessing
o  additionalFolderItemsInMenu
any additional folders to be shown in the 'File' menu;
each element can be either a filename or a pair with filename and menu-item-label.

Usage example(s): 

FileDialog additionalFolderItemsInMenu:#('/Users/exept' ('/Users/exept/cg_work' 'WorkDir'))

o  additionalFolderItemsInMenu: aCollectionOfFoldernames
any additional folders to be shown in every 'File' menu;
each element can be either a filename or a pair with filename and menu-item-label,
or an assoc, with key=filename and value=label.

Usage example(s): 

FileDialog additionalFolderItemsInMenu:#('/Users/exept' ('/Users/exept/cg_work' 'WorkDir'))

o  additionalFoldersInDirectoryMenuQuery
can be answered with a list of addotional folders
(expecco does this to add eg/ the attach,emtsFolder(

Usage example(s): 

     FileDialog additionalFoldersInDirectoryMenuQuery 
        answer:#('/foo' '/bar')
        do:[
            Dialog requestFileName:'Enter filename'
        ]

o  classResources
(comment from inherited method)
if not already loaded, get the classes resourcePack and return it

o  lastExtent
marked as obsolete by exept MBP at 10-06-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  lastExtent: anExtent
marked as obsolete by exept MBP at 10-06-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  setDoubleClickActionFor: instance

help specs
o  helpSpec
This resource specification was automatically generated
by the UIHelpTool of ST/X.

instance creation
o  requestDirectoryName: title default: aFileName ifFail: failBlock
same as requestFileName, but only show directories

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName
        ifFail:'none'

o  requestDirectoryName: title default: aFileName ok: okText abort: abortText ifFail: failBlock
same as requestFileName, but only show directories

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName
        ok:'Yes'
        abort:'No'
        ifFail:'none'

o  requestDirectoryName: title default: aFileName ok: okText abort: abortText ifFail: failBlock acceptReturnAsOK: aBoolean
same as requestFileName, but only show directories

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName
        ok:'Yes'
        abort:'No'
        ifFail:'none'

o  requestDirectoryName: titleString default: aFileName ok: okText abort: abortText version: versionSymbol pattern: patternArg fromDirectory: aDirectoryPath ifFail: failBlock whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: aBoolean
same as requestFileName, but only show directories

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName
        ifFail:nil

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName 
        ok:nil
        abort:nil 
        version:nil 
        pattern:nil 
        fromDirectory:nil 
        ifFail:nil 
        whenBoxCreatedEvaluate:nil
        asLoadDialog:true

o  requestDirectoryName: title default: aFileName ok: okText ifFail: failBlock
same as requestFileName, but only show directories

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName
        ok:'Yes'
        ifFail:'none'

o  requestFileName: titleString default: defaultName ok: okText abort: abortText pattern: pattern fromDirectory: aDirectoryPathOrNil
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return the string, or nil if cancel was pressed.

o  requestFileName: titleString default: defaultName ok: okText abort: abortText pattern: pattern fromDirectory: aDirectoryPathOrNil whenBoxCreatedEvaluate: boxCreatedCallback

o  requestFileName: titleString default: defaultName ok: okText abort: abortText version: versionSymbol ifFail: failBlock pattern: pattern fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return the string, or nil if cancel was pressed
The version argument allows validation of the files existance;
it may be any of:
#mustBeNew - fail (return empty string) if the file exists
#new - confirm if the file exists
#mustBeOld - fail if the file does not exist
#old - confirm if the file does not exist
#any (other) - no validation

o  requestFileName: titleString default: defaultName ok: okText abort: abortText version: versionSymbol ifFail: failBlock pattern: patternArg fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: aBoolean
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return the string, or nil if cancel was pressed
The version argument allows validation of the files existance;
it may be any of:
#mustBeNew - fail (return empty string) if the file exists
#new - confirm if the file exists
#mustBeOld - fail if the file does not exist
#old - confirm if the file does not exist
#any (other) - no validation

Usage example(s): 

     FileDialog 
        requestFileName:'enter a fileName:'
        default:''
        ok:nil 
        abort:nil
        version:nil
        ifFail:['none']
        pattern:'*'
        fromDirectory:Filename currentDirectory pathName
        whenBoxCreatedEvaluate:nil
        asLoadDialog:true

o  requestFileName: titleString default: defaultName pattern: pattern fromDirectory: aDirectory
launch a Dialog, which allows user to enter a filename.
The files presented initially are those from the current directory.
The box will show ok/cancel in its buttons.
The matchPattern is set to pattern initially.
Return the string or nil if cancel was pressed.

o  requestFileName: titleString default: defaultName version: versionSymbol ifFail: failBlock pattern: pattern fromDirectory: aDirectoryPathOrNil whenBoxCreatedEvaluate: boxCreatedCallback
FileDialog
requestFileName:'enter a fileName:'
default:''
version:nil
ifFail:['none']
pattern:'*.conf'
fromDirectory:Filename currentDirectory pathName
whenBoxCreatedEvaluate:nil.
Dialog
requestFileName:'enter a fileName:'
default:''
version:nil
ifFail:['none']
pattern:'*.conf'
fromDirectory:Filename currentDirectory pathName
whenBoxCreatedEvaluate:nil

Usage example(s): 

     FileDialog
        requestFileName:'enter a fileName:'
        default:''
        version:#old 
        ifFail:['none']   
        pattern:'*.conf'
        fromDirectory:Filename currentDirectory pathName
        whenBoxCreatedEvaluate:nil

Usage example(s): 

     FileDialog
        requestFileName:'enter a fileName:'
        default:''
        version:#mustBeNew 
        ifFail:['none']   
        pattern:'*.conf'
        fromDirectory:Filename currentDirectory pathName
        whenBoxCreatedEvaluate:nil

o  requestFileNames: titleString default: defaultName ok: okText abort: abortText ifFail: failBlock pattern: pattern fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return all selected Filenames as filenames in a collection, or nil if cancel was pressed

Usage example(s): 

     FileDialog 
        requestFileNames:'enter a fileName:'
        default:''
        ok:nil 
        abort:nil 
        ifFail:['none']
        pattern:'*.conf'
        fromDirectory:Filename currentDirectory pathName
        whenBoxCreatedEvaluate:nil.

o  requestFileNames: titleString default: defaultName ok: okText abort: abortText ifFail: failBlock pattern: patternArg fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: asLoadDialog
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return all selected Filenames as filenames in a collection, or nil if cancel was pressed

Usage example(s): 

     FileDialog 
        requestFileNames:'enter a fileName:'
        default:''
        ok:nil 
        abort:nil 
        ifFail:['none']
        pattern:'*.conf'
        fromDirectory:Filename currentDirectory pathName
        whenBoxCreatedEvaluate:nil
        asLoadDialog:true.

o  startApplicationFor: titleString default: initialDefaultFileNameArg ok: okTextArg abort: abortTextArg ifFail: failBlock pattern: patternArg fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: asLoadDialog viewFiles: viewFilesArg multipleSelect: multipleSelectArg
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return the string, or nil if cancel was pressed
The version argument allows validation of the files existance;
it may be any of:
#mustBeNew - fail (return empty string) if the file exists
#new - confirm if the file exists
#mustBeOld - fail if the file does not exist
#old - confirm if the file does not exist
#any (other) - no validation

interface specs
o  windowSpec
This resource specification was automatically generated
by the UIPainter of ST/X.

Usage example(s): 

     UIPainter new openOnClass:FileDialog andSelector:#windowSpec
     FileDialog new openInterface:#windowSpec
     FileDialog open

menu specs
o  directoryMenu
This resource specification was automatically generated
by the MenuEditor of ST/X.

o  mainMenu
This resource specification was automatically generated
by the MenuEditor of ST/X.

Usage example(s): 

     MenuEditor new openOnClass:FileDialog andSelector:#mainMenu
     (Menu new fromLiteralArrayEncoding:(FileDialog mainMenu)) startUp

o  toolBarMenu
This resource specification was automatically generated
by the MenuEditor of ST/X.

Usage example(s): 

     MenuEditor new openOnClass:FileDialog andSelector:#toolBarMenu
     (Menu new fromLiteralArrayEncoding:(FileDialog toolBarMenu)) startUp

o  viewInContentsBrowserMenu

plugIn spec
o  aspectSelectors
This resource specification was automatically generated
by the UIPainter of ST/X.

Instance protocol:

API
o  requestDirectoryName: titleString default: aFileName ok: okText abort: abortText version: versionSymbol pattern: patternArg fromDirectory: aDirectoryPath ifFail: failBlock whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: aBoolean
same as requestFileName, but only show directories

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName
        ifFail:nil

Usage example(s): 

     FileDialog
        requestDirectoryName:'which directory ?' 
        default:Filename currentDirectory pathName 
        ok:nil
        abort:nil 
        version:nil 
        pattern:nil 
        fromDirectory:nil 
        ifFail:nil 
        whenBoxCreatedEvaluate:nil
        asLoadDialog:true

o  requestFileName: titleString default: defaultName ok: okText abort: abortText version: versionSymbol ifFail: failBlock pattern: patternArg fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: aBoolean
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return the string, or nil if cancel was pressed (or an empty filename was entered)
The version argument allows validation of the files existance;
it may be any of:
#mustBeNew - fail (return empty string) if the file exists
#new - confirm if the file exists
#mustBeOld - fail if the file does not exist
#old - confirm if the file does not exist
#any (other) - no validation

Usage example(s): 

     FileDialog 
        requestFileName:'enter a fileName:'
        default:''
        ok:nil 
        abort:nil
        version:nil
        ifFail:['none']
        pattern:'*'
        fromDirectory:Filename currentDirectory pathName
        whenBoxCreatedEvaluate:nil
        asLoadDialog:true

o  requestFileNames: titleString default: defaultName ok: okText abort: abortText ifFail: failBlock pattern: patternArg fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: asLoadDialog
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to pattern initially.
Return all selected Filenames as filenames in a collection, or nil if cancel was pressed

Usage example(s): 

     FileDialog 
        requestFileNames:'enter a fileName:'
        default:''
        ok:nil 
        abort:nil 
        ifFail:['none']
        pattern:'*.conf'
        fromDirectory:Filename currentDirectory pathName
        whenBoxCreatedEvaluate:nil
        asLoadDialog:true.

o  startApplicationFor: titleString default: initialDefaultFileNameArg ok: okTextArg abort: abortTextArg ifFail: failBlock pattern: patternArg fromDirectory: aDirectoryPath whenBoxCreatedEvaluate: boxCreatedCallback asLoadDialog: asLoadDialog viewFiles: viewFilesArg multipleSelect: multipleSelectArg
launch a Dialog, which allows user to enter a filename.
The files presented initially are those in aDirectoryPathOrNil, or the
last fileBox directory (default: current directory) (if a nil path is given).
The box will show okText in its okButton, abortText in the abortButton.
The matchPattern is set to patternArg initially.
Return the string, or nil if cancel was pressed
The version argument allows validation of the files existance;
it may be any of:
#mustBeNew - fail (return empty string) if the file exists
#new - confirm if the file exists
#mustBeOld - fail if the file does not exist
#old - confirm if the file does not exist
#any (other) - no validation

accessing
o  additionalFolderItemsInMenu: aCollectionOfFoldernames
any additional folders to be shown in this 'File' menu;
each element can be either a filename or a pair with filename and menu-item-label,
or an assoc, with key=filename and value=label.

o  appendWasPressed
valid after the dialog has been closed: true if append was pressed

o  currentSelectedFiles

o  directory
return the value of the instance variable 'directory' (automatically generated)

o  directory: something
set the value of the instance variable 'directory' (automatically generated)

o  initialText

o  initialText: something

o  pattern
return the value of the instance variable 'pattern' (automatically generated)

o  pattern: aString
set the matchpattern

o  result
return the value of the instance variable 'result' (automatically generated)

o  result: something
set the value of the instance variable 'result' (automatically generated)

o  selectedDirectories

o  startFilename

o  startFilename: something

accessing-behavior
o  asLoadDialog
marked as obsolete by mobile at 03-08-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asLoadDialog: aBoolean
marked as obsolete by mobile at 03-08-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  beLoadDialog: aBoolean

o  doubleClickAction
return the value of the instance variable 'doubleClickAction' (automatically generated)

o  doubleClickAction: something
set the value of the instance variable 'doubleClickAction' (automatically generated)

o  isLoadDialog

o  multipleSelect

o  multipleSelect: aBoolean

accessing-components
o  addButton: aButton

o  okButton

o  treeBrowser
return the value of the instance variable 'treeBrowser' (automatically generated)

o  verticalPanel

accessing-look
o  hideButtonPanel

o  showButtonPanel

o  viewFiles
if true, files can be selected; if false, only directories

o  viewFiles: aBoolean
if true, files can be selected; if false, only directories

aspects
o  appendButtonVisibleHolder
if set, an additional 'append' button is shown
(to let user append to a file, instead of overwriting the file)

o  appendLabelHolder

o  aspectOrNil: aKey forSubApplication: aSubApp
this hook provides an aspect for a subApp

o  browseMenuItemVisible: aBoolean
controls if an 'open filebrowser' menu item is to be shown in the toolbar

o  browseMenuItemVisibleHolder
controls if an 'open filebrowser' menu item is to be shown in the toolbar

o  buttonPanelVisibleHolder

o  cancelLabelHolder

o  enableBack

o  enableDirectoryUp

o  enableForward

o  enableGotoDesktopDirectory

o  enableGotoDocuments

o  enableGotoDownloads

o  enableHome

o  fileEntryFieldHolder
for directoryTreeBrowser

o  filenameHolder
Return a value holder with the filename.
Shown in the filename input-field.
Being the selection in the tree.

o  filenameHolder: aHolder
needed when used as subcanvas

o  filenameLabelHolder
Return a value holder for the input string.

o  filterHolder
Return a value holder for filter

o  filterHolder: aHolder
needed when used as subcanvas

o  gotoBookmarksMenu
|menu bookmarks|

o  listOfDeviceDrives

o  newDirectoryVisibilityHolder

o  okLabelEnabled

o  okLabelHolder

o  rootDirectoryHolder
Return a value holder for filter

o  rootDirectoryHolder: aHolder
Return a value holder for filter

o  searchInfoBoxVisibleHolder
set during search-file operation

o  searchedDirectoryInfoHolder
updated during search-file operation

o  selectedDeviceDrive

o  showDirectoryTree

o  showDiskUsageHolder

o  showHiddenFiles

o  shownFiles

o  sortCaseless
aspect for sort caseless

o  sortCaselessInTreeBrowser
only for backward compat.
We do not need two such flags

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  sortInTreeVisibilityHolder

o  sortPropertyInTree

o  viewDirsInContentsBrowser

o  viewFilesInDirectoryTree

o  viewNoteBookApplicationHolder

change & update
o  buttonPanelVisibilityChanged
force resize

o  fileSelectionChanged
the name in the entry field

o  selectedDeviceDriveChanged
Filename defaultVolumeName.

o  update: something with: aParameter from: changedObject
(comment from inherited method)
dependent is notified of some change -
Default is to try update:with:

construction-adding
o  addComponent: aView

event handling
o  processEvent: anEvent
filter keyboard edit-events typed into the listOfItemsView.
Return true, if I have eaten the event

initialization & release
o  commonPostOpen
self windowGroup addPreEventHook:self.

o  initialRootDirectory
returns the directory the browser is open on

o  initialize
false

o  postBuildFileNameField: aWidget

o  postBuildFilterField: aWidget

o  postBuildTreeBrowser: aSubCanvasView

o  postBuildVerticalPanelView: aView

o  postBuildWith: aBuilder
minExtent is nil if window is not a TopView

o  postOpenAsSubcanvasWith: aBuilder
No ok and cancel buttons, when dialog is part of a larger dialog

o  preOpenWith: aBuilder
called right before being opened

o  rememberExtent
marked as obsolete by exept MBP at 10-06-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

menus
o  additionalFoldersMenuSlice
AdditionalFolderItemsInMenu := #('/foo' '/etc' '/Users')

o  additionalFoldersMenuSliceHolder

o  bookmarksMenu

o  directoryMenu

o  showMenuSpecForDialog

o  sortMenu

o  visitedDirectoriesMenu

private
o  returnWasPressedInFilterField
ev targetView isSameOrComponentOf:filenameField

o  returnWasPressedInFilterOrFilenameField
ev targetView isSameOrComponentOf:filenameField

queries
o  driveSelectorVisible

user actions
o  appendPressed

o  commonAcceptAction

o  doAccept
force accept - ignore in filterField

o  doBack

o  doBrowseDirectory

o  doCancel
(comment from inherited method)
force cancel

o  doFindAndSelectFile
search for a file matching a requested pattern

o  doFindAndSelectNextFile
search the next file matching the previous pattern

o  doForward

o  doGoDirectoryUp

o  doGotoDesktopDirectory

o  doGotoDocumentsDirectory

o  doGotoDownloadsDirectory

o  doGotoHomeDirectory

o  expandSelectionIfShowingFiles

o  findAndSelectNextFileEnabledHolder

o  gotoFile: fn

o  menuDirHistory: backOrForward

o  menuDirHistoryBack

o  menuDirHistoryForward

o  newDirectory
forward to the treebrowser component, which already has this functionality

o  okPressed

o  openTerminal
forward to the treebrowser component, which already has this functionality

o  tabPressedInFilenameField

o  updateCurrentDirectory

Private classes:

    AdditionalFoldersInDirectoryMenuQuery

Examples:


usually direct access to FileDialog is not recommended; please use the Dialog interface, which is able to dispatch to alternative file choosers if the settings say so (native dialogs, for example): 
  |fileOrNil|

  fileOrNil := Dialog requestFileName:'Choose a File'.
  Transcript showCR:fileOrNil
simple examples: 
  FileDialog 
      requestFileName:'enter a fileName:'
      default:''
      version:nil
      ifFail:['none']
      pattern:'*.conf'
      fromDirectory:'/etc'
      whenBoxCreatedEvaluate:nil.

  |fd|

  fd := FileDialog new.
  fd multipleSelect:true.
  fd open

  |fd|

  fd := FileDialog new.
  fd multipleSelect:true.
  fd browseMenuItemVisible:false.
  fd open
Adding custom components: 
  Dialog modifyingBoxWith:[:dialog |
      | fmtBox |

      fmtBox := ComboListView new.
      fmtBox list: #('Comma Separated Values (.csv)'
                      'Microsoft Excel (.xls)'
                      'Microsoft Excel XML (.xlsx)') .
      fmtBox model:'Select...' asValue.
      dialog application addComponent: fmtBox.
  ] do:[
      Dialog requestFileName: 'Save file as...'
  ]

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 22 Dec 2024 02:04:29 GMT